@intlayer/engine 9.5.9 → 9.5.11

package/dist/esm/scan/checks.mjs

@@ -1,265 +1,432 @@
-import { extractHreflangs, extractHtmlDir, extractHtmlLang, hasCanonical } from "./parseHtml.mjs";
+import { fetchText } from "./fetchText.mjs";
+import { isAbsoluteUrl, normalizeUrl, parseUrl } from "./detection/url.mjs";
+import { extractHreflangs, extractHtmlLang } from "./parseHtml.mjs";
 import { analyzeBundleContent } from "./analyzeBundleContent.mjs";
-import { ALL_LOCALES } from "@intlayer/types/allLocales";
+import { getLanguageCode, isRightToLeftLocale, isSameLanguage, isValidLocaleCode, isValidOpenGraphLocale, normalizeLocaleCode, toOpenGraphLocale } from "./detection/localeCode.mjs";
+import { getUrlLocale } from "./detection/detectRoutingStrategy.mjs";
+import { classifyInternalLinks } from "./detection/classifyInternalLinks.mjs";
+import { isPathAllowedByRobots, parseRobots } from "./robots.mjs";
+import { collectSitemapEntries, getDefaultSitemapUrls } from "./sitemap.mjs";
 
 //#region src/scan/checks.ts
+/** Maximum number of links listed in a check's details. */
+const MAX_LISTED_LINKS = 30;
+/** Maximum number of hreflang alternates fetched for the reciprocity check. */
+const MAX_FETCHED_ALTERNATES = 8;
+/** Statuses meaning the site refuses automated requests, not a broken page. */
+const BOT_BLOCKING_STATUSES = /* @__PURE__ */ new Set([
+	401,
+	403,
+	429
+]);
 /** Format a byte count as a human-readable size. */
 const formatSize = (bytes) => {
 	if (bytes >= 1048576) return `${(bytes / 1048576).toFixed(2)} MB`;
 	if (bytes >= 1024) return `${(bytes / 1024).toFixed(2)} KB`;
 	return `${bytes} B`;
 };
+/** Build a URL-scoped check type (`url_htmlLang\https://…`). */
+const urlCheckType = (checkName, targetUrl) => `${checkName}\\${targetUrl}`;
+/** Emit an event whose details are attached to its own status. */
+const emitCheck = (emit, type, status, details) => emit({
+	type,
+	status,
+	details: details === void 0 ? void 0 : { [status]: details }
+});
+/** Render an anchor as an HTML line for the details popover. */
+const formatAnchor = ({ href, text }) => `<a href="${href}">${text.slice(0, 60) || "Link"}</a>`;
+/** `url_htmlLang`: `<html lang>` is present and a valid BCP 47 tag. */
+const checkHtmlLang = ({ targetUrl, langTag }, emit) => {
+	const type = urlCheckType("url_htmlLang", targetUrl);
+	if (!langTag) emitCheck(emit, type, "error", "Missing html lang attribute");
+	else if (!isValidLocaleCode(langTag)) emitCheck(emit, type, "error", `"${langTag}" is not a valid BCP 47 language tag (expected e.g. "en" or "en-US")`);
+	else emitCheck(emit, type, "success", langTag);
+};
 /**
-* Check the `<html>` element attributes (`lang`, `dir`) and the resulting
-* current-locale signal. Returns the detected language tag.
+* `url_htmlDir`: the text direction matches the language. `dir` is only
+* required for right-to-left languages, `ltr` being the browser default.
 */
-const checkHtmlAttributes = (html, targetUrl, events) => {
-	const langTag = extractHtmlLang(html);
-	const dirTag = extractHtmlDir(html);
-	events.push({
-		type: `url_htmlLang\\${targetUrl}`,
-		status: langTag ? "success" : "error",
-		details: {
-			success: langTag,
-			error: langTag ? void 0 : "Missing html lang attribute"
-		}
-	});
-	events.push({
-		type: `url_currentLocale\\${targetUrl}`,
-		status: langTag ? "success" : "warning",
-		details: {
-			success: langTag,
-			warning: langTag ? void 0 : "No locale detected"
-		}
-	});
-	events.push({
-		type: `url_htmlDir\\${targetUrl}`,
-		status: dirTag ? "success" : "warning",
-		details: {
-			success: dirTag,
-			warning: dirTag ? void 0 : "Missing html dir attribute"
-		}
-	});
-	return { langTag };
+const checkHtmlDir = ({ targetUrl, langTag, dirTag }, emit) => {
+	const type = urlCheckType("url_htmlDir", targetUrl);
+	const direction = dirTag?.toLowerCase();
+	if (!langTag) {
+		emitCheck(emit, type, "warning", "Cannot verify the text direction: html lang is missing");
+		return;
+	}
+	const expectedDirection = isRightToLeftLocale(langTag) ? "rtl" : "ltr";
+	if (direction === expectedDirection || !direction && expectedDirection === "ltr") {
+		emitCheck(emit, type, "success", direction ?? "ltr (browser default)");
+		return;
+	}
+	emitCheck(emit, type, "error", direction ? `dir="${direction}" does not match the ${expectedDirection.toUpperCase()} language "${langTag}"` : `Missing dir="rtl" for the right-to-left language "${langTag}"`);
 };
-/** Check the presence of a canonical link. */
-const checkCanonical = (html, targetUrl, events) => {
-	const present = hasCanonical(html);
-	events.push({
-		type: `url_hasCanonical\\${targetUrl}`,
-		status: present ? "success" : "warning",
-		details: { warning: present ? void 0 : "Missing canonical link" }
+/**
+* `url_currentLocale`: the locale announced by `<html lang>`, the URL and the
+* self hreflang entry agree.
+*/
+const checkLocaleConsistency = ({ targetUrl, langTag, hreflangs, routing }, emit) => {
+	const type = urlCheckType("url_currentLocale", targetUrl);
+	const normalizedTargetUrl = normalizeUrl(targetUrl);
+	const selfHreflang = hreflangs.find(({ hreflang, href }) => hreflang.toLowerCase() !== "x-default" && normalizeUrl(href, targetUrl) === normalizedTargetUrl)?.hreflang;
+	const signals = {
+		htmlLang: langTag,
+		urlLocale: routing.urlLocale,
+		selfHreflang
+	};
+	const definedLocales = Object.values(signals).filter((locale) => Boolean(locale));
+	if (definedLocales.length === 0) {
+		emitCheck(emit, type, "warning", "No locale detected on the page");
+		return;
+	}
+	const firstLocale = definedLocales[0];
+	const isConsistent = definedLocales.every((locale) => isSameLanguage(locale, firstLocale));
+	emitCheck(emit, type, isConsistent ? "success" : "error", isConsistent ? signals : {
+		message: "The page announces different locales in html lang, its URL and its hreflang entry",
+		...signals
 	});
 };
+/** Describe an invalid Open Graph locale, with the value to use instead. */
+const formatInvalidOpenGraphLocale = (localeCode, langTag, property) => {
+	const suggestion = toOpenGraphLocale(localeCode, langTag);
+	return `${property} "${localeCode}" is not a valid Open Graph locale (expected language_TERRITORY${suggestion ? `, e.g. "${suggestion}"` : ""}): crawlers ignore it and fall back to en_US`;
+};
 /**
-* Check the page's hreflang structure and collect discovered locales into
-* `localesSet`.
+* `url_ogLocale`: `og:locale` is set, uses the Open Graph `language_TERRITORY`
+* format (`en_GB`, not `en` nor `en-GB`) and matches `<html lang>`.
+* `og:locale:alternate` values must use the same format.
 */
-const checkLinguisticStructure = (html, targetUrl, localesSet, events) => {
-	const langTag = extractHtmlLang(html);
-	if (langTag) localesSet.add(langTag);
-	const hreflangs = extractHreflangs(html);
-	for (const { hreflang } of hreflangs) if (hreflang !== "x-default") localesSet.add(hreflang);
-	const hasXDefault = hreflangs.some((h) => h.hreflang === "x-default");
-	events.push({
-		type: `url_hreflang\\${targetUrl}`,
-		status: hreflangs.length > 0 ? "success" : "warning",
-		details: {
-			success: hreflangs.length > 0 ? hreflangs : void 0,
-			warning: hreflangs.length === 0 ? "No hreflang tags found" : void 0
-		}
-	});
-	events.push({
-		type: `url_hasXDefault\\${targetUrl}`,
-		status: hasXDefault ? "success" : "error",
-		details: { error: hasXDefault ? void 0 : "Missing x-default hreflang link" }
+const checkOgLocale = ({ targetUrl, ogLocale, ogLocaleAlternates = [], langTag }, emit) => {
+	const type = urlCheckType("url_ogLocale", targetUrl);
+	if (!ogLocale) {
+		emitCheck(emit, type, "warning", "Missing <meta property=\"og:locale\">: social previews default to en_US");
+		return;
+	}
+	if (!isValidOpenGraphLocale(ogLocale)) {
+		emitCheck(emit, type, "error", formatInvalidOpenGraphLocale(ogLocale, langTag, "og:locale"));
+		return;
+	}
+	if (langTag && !isSameLanguage(ogLocale, langTag)) {
+		emitCheck(emit, type, "warning", `og:locale "${ogLocale}" does not match html lang "${langTag}"`);
+		return;
+	}
+	const invalidAlternates = ogLocaleAlternates.filter((alternate) => !isValidOpenGraphLocale(alternate));
+	if (invalidAlternates.length > 0) {
+		emitCheck(emit, type, "warning", invalidAlternates.map((alternate) => formatInvalidOpenGraphLocale(alternate, void 0, "og:locale:alternate")).join("\n"));
+		return;
+	}
+	emitCheck(emit, type, "success", ogLocale);
+};
+/**
+* `url_hasCanonical`: a canonical link exists and does not point to another
+* locale version (which would de-index the current one).
+*/
+const checkCanonical = ({ targetUrl, canonicalHref, hreflangs, routing, pageLocale }, emit) => {
+	const type = urlCheckType("url_hasCanonical", targetUrl);
+	if (canonicalHref === void 0 || canonicalHref === "") {
+		emitCheck(emit, type, "warning", "Missing canonical link");
+		return;
+	}
+	const canonicalUrl = normalizeUrl(canonicalHref, targetUrl);
+	const otherLocaleAlternate = hreflangs.find(({ hreflang, href }) => hreflang.toLowerCase() !== "x-default" && normalizeUrl(href, targetUrl) === canonicalUrl && !isSameLanguage(hreflang, pageLocale));
+	const canonicalLocale = getUrlLocale(canonicalUrl, routing);
+	if (otherLocaleAlternate || canonicalLocale && pageLocale && !isSameLanguage(canonicalLocale, pageLocale)) {
+		emitCheck(emit, type, "error", {
+			message: `The canonical URL points to the "${otherLocaleAlternate?.hreflang ?? canonicalLocale}" version instead of this "${pageLocale}" page: search engines will drop this page from their index`,
+			canonical: canonicalUrl
+		});
+		return;
+	}
+	emitCheck(emit, type, "success", canonicalUrl === normalizeUrl(targetUrl) ? canonicalUrl : {
+		message: "Canonical points to another URL of the same locale",
+		canonical: canonicalUrl
 	});
 };
-const normalizeHost = (host) => host.startsWith("www.") ? host.slice(4) : host;
-const localeValues = Object.values(ALL_LOCALES);
 /**
-* Check whether internal links carry a locale segment, mirroring the hosted
-* audit's URL-structure analysis but operating on parsed anchors instead of a
-* live DOM.
+* `url_hreflang`: hreflang tags exist, use valid codes and absolute URLs, have
+* no duplicates, and include a self reference.
 */
-const checkUrlStructure = (anchors, origin, targetUrl, events) => {
-	const targetHostname = normalizeHost(new URL(origin).hostname);
-	let localizedCount = 0;
-	let totalInternalCount = 0;
-	const nonLocalizedLinks = [];
-	for (const { href } of anchors) {
-		if (!href || href.startsWith("#") || href.startsWith("javascript:")) continue;
-		try {
-			const url = new URL(href, origin);
-			if (normalizeHost(url.hostname) !== targetHostname) continue;
-			totalInternalCount++;
-			const path = url.pathname.toLowerCase();
-			const hostname = url.hostname.toLowerCase();
-			const hasLocaleInPath = localeValues.some((locale) => {
-				const l = locale.toLowerCase();
-				return path === `/${l}` || path.includes(`/${l}/`);
-			});
-			const hasLocaleInSubdomain = localeValues.some((locale) => {
-				const l = locale.toLowerCase();
-				return hostname.startsWith(`${l}.`) || hostname.includes(`.${l}.`);
-			});
-			if (hasLocaleInPath || hasLocaleInSubdomain) localizedCount++;
-			else nonLocalizedLinks.push(href);
-		} catch {}
+const checkHreflang = ({ targetUrl, hreflangs, canonicalHref }, emit) => {
+	const type = urlCheckType("url_hreflang", targetUrl);
+	if (hreflangs.length === 0) {
+		emitCheck(emit, type, "warning", "No hreflang tags found");
+		return;
 	}
-	const hasLocalizedLinks = localizedCount > 0;
-	const allAnchorsLocalized = totalInternalCount === 0 || localizedCount === totalInternalCount;
-	events.push({
-		type: `url_hasLocalizedLinks\\${targetUrl}`,
-		status: hasLocalizedLinks ? "success" : "warning",
-		details: {
-			success: hasLocalizedLinks ? `${localizedCount} localized links found out of ${totalInternalCount} internal links` : void 0,
-			warning: hasLocalizedLinks ? void 0 : "No localized links found"
-		}
+	const issues = [];
+	const invalidCodes = hreflangs.map(({ hreflang }) => hreflang).filter((hreflang) => !isValidLocaleCode(hreflang));
+	if (invalidCodes.length > 0) issues.push(`Invalid hreflang codes: ${invalidCodes.join(", ")}`);
+	const ukCodes = hreflangs.map(({ hreflang }) => hreflang).filter((hreflang) => /-uk$/i.test(hreflang));
+	if (ukCodes.length > 0) issues.push(`"${ukCodes.join(", ")}": the United Kingdom region code is "GB" (e.g. en-GB)`);
+	const relativeHrefs = hreflangs.filter(({ href }) => !isAbsoluteUrl(href));
+	if (relativeHrefs.length > 0) issues.push(`hreflang URLs must be absolute (https://…), search engines ignore: ${relativeHrefs.map(({ hreflang, href }) => `${hreflang} → ${href}`).join(", ")}`);
+	const urlsByCode = /* @__PURE__ */ new Map();
+	for (const { hreflang, href } of hreflangs) {
+		const code = normalizeLocaleCode(hreflang);
+		const urls = urlsByCode.get(code) ?? /* @__PURE__ */ new Set();
+		urls.add(normalizeUrl(href, targetUrl));
+		urlsByCode.set(code, urls);
+	}
+	const conflictingCodes = [...urlsByCode.entries()].filter(([, urls]) => urls.size > 1).map(([code]) => code);
+	if (conflictingCodes.length > 0) issues.push(`Same hreflang declared with different URLs: ${conflictingCodes.join(", ")}`);
+	const selfUrls = /* @__PURE__ */ new Set([normalizeUrl(targetUrl)]);
+	if (canonicalHref) selfUrls.add(normalizeUrl(canonicalHref, targetUrl));
+	if (!hreflangs.some(({ hreflang, href }) => hreflang.toLowerCase() !== "x-default" && selfUrls.has(normalizeUrl(href, targetUrl)))) issues.push("No hreflang entry points to the page itself (self reference)");
+	const status = relativeHrefs.length > 0 ? "error" : issues.length > 0 ? "warning" : "success";
+	emitCheck(emit, type, status, issues.length > 0 ? {
+		issues,
+		hreflangs
+	} : hreflangs);
+};
+/** `url_hasXDefault`: an `x-default` hreflang is declared. */
+const checkXDefault = ({ targetUrl, hreflangs }, emit) => {
+	const type = urlCheckType("url_hasXDefault", targetUrl);
+	const xDefault = hreflangs.find(({ hreflang }) => hreflang.toLowerCase() === "x-default");
+	if (xDefault) emitCheck(emit, type, "success", xDefault.href);
+	else if (hreflangs.length === 0) emitCheck(emit, type, "warning", "No hreflang tags, so no x-default either");
+	else emitCheck(emit, type, "error", "Missing x-default hreflang link");
+};
+/** Fetch an alternate and check it forms a valid hreflang pair with the page. */
+const verifyAlternate = async (alternateUrl, hreflang, selfUrls, fetchOptions) => {
+	const response = await fetchText(alternateUrl, fetchOptions);
+	const verification = {
+		url: alternateUrl,
+		hreflang
+	};
+	if (!response || BOT_BLOCKING_STATUSES.has(response.status)) return {
+		...verification,
+		outcome: "unverifiable",
+		issues: []
+	};
+	if (!response.ok) return {
+		...verification,
+		outcome: "broken",
+		issues: [`HTTP ${response.status}`]
+	};
+	const issues = [];
+	if (response.redirected) issues.push(`redirects to ${response.finalUrl}`);
+	if (!extractHreflangs(response.text).some(({ href }) => selfUrls.has(normalizeUrl(href, response.finalUrl)))) issues.push("no hreflang link back to this page");
+	const alternateLang = extractHtmlLang(response.text);
+	if (alternateLang && !isSameLanguage(alternateLang, hreflang)) issues.push(`html lang is "${alternateLang}"`);
+	return {
+		...verification,
+		outcome: issues.length > 0 ? "invalid" : "valid",
+		issues
+	};
+};
+/**
+* `url_hreflangReciprocal`: every alternate answers with a 200, is not
+* redirected, links back to this page and declares the expected language.
+* Search engines ignore hreflang pairs without a return link.
+*/
+const checkHreflangReciprocity = async ({ targetUrl, hreflangs, canonicalHref }, fetchOptions, emit) => {
+	const type = urlCheckType("url_hreflangReciprocal", targetUrl);
+	const selfUrls = /* @__PURE__ */ new Set([normalizeUrl(targetUrl)]);
+	if (canonicalHref) selfUrls.add(normalizeUrl(canonicalHref, targetUrl));
+	const alternatesByUrl = /* @__PURE__ */ new Map();
+	for (const { hreflang, href } of hreflangs) {
+		if (hreflang.toLowerCase() === "x-default") continue;
+		const absoluteUrl = parseUrl(href, targetUrl)?.href;
+		if (!absoluteUrl || selfUrls.has(normalizeUrl(absoluteUrl))) continue;
+		if (!alternatesByUrl.has(absoluteUrl)) alternatesByUrl.set(absoluteUrl, hreflang);
+	}
+	if (alternatesByUrl.size === 0) return;
+	const verifications = await Promise.all([...alternatesByUrl.entries()].slice(0, MAX_FETCHED_ALTERNATES).map(([alternateUrl, hreflang]) => verifyAlternate(alternateUrl, hreflang, selfUrls, fetchOptions)));
+	const unverifiableUrls = verifications.filter(({ outcome }) => outcome === "unverifiable").map(({ url }) => url);
+	const failingVerifications = verifications.filter(({ outcome }) => outcome === "broken" || outcome === "invalid");
+	const verifiedCount = verifications.length - unverifiableUrls.length;
+	if (verifiedCount === 0) {
+		emitCheck(emit, type, "warning", {
+			message: "The alternates could not be verified: they are unreachable or block automated requests",
+			urls: unverifiableUrls
+		});
+		return;
+	}
+	if (failingVerifications.length === 0) {
+		emitCheck(emit, type, "success", `${verifiedCount} alternates checked, all reciprocal`);
+		return;
+	}
+	emitCheck(emit, type, failingVerifications.some(({ outcome }) => outcome === "broken") ? "error" : "warning", {
+		message: `${failingVerifications.length} of ${verifiedCount} checked hreflang alternates are not valid return pairs`,
+		alternates: failingVerifications.map(({ hreflang, url, issues }) => `${hreflang} ${url}: ${issues.join(", ")}`),
+		unverifiableUrls
 	});
-	events.push({
-		type: `url_allAnchorsLocalized\\${targetUrl}`,
-		status: allAnchorsLocalized ? "success" : "warning",
-		details: { warning: allAnchorsLocalized ? void 0 : {
-			message: "Some internal links are not localized",
-			links: nonLocalizedLinks
-		} }
+};
+/**
+* Link checks, interpreted through the detected routing strategy (so an
+* unprefixed link is correct on the default locale of a `prefix-no-default`
+* site, and `?lang=` links are understood on `search-params` sites):
+*
+* - `url_hasLocalizedLinks`: internal links keep the page locale
+* - `url_allAnchorsLocalized`: no internal link loses or switches the locale
+* - `url_hasLangSelector`: crawlable links to the other locale versions exist
+*/
+const checkInternalLinks = (signals, emit) => {
+	const { targetUrl, routing, pageLocale } = signals;
+	const { internalLinks, sameLocaleLinks, otherLocaleLinks, unlocalizedLinks, switcherLinks } = classifyInternalLinks(signals);
+	const listLinks = (links) => links.slice(0, MAX_LISTED_LINKS).map(formatAnchor);
+	const localizedLinksType = urlCheckType("url_hasLocalizedLinks", targetUrl);
+	const isLocaleInUrl = routing.strategy !== "no-prefix" && routing.strategy !== "unknown";
+	if (internalLinks.length === 0) emitCheck(emit, localizedLinksType, "warning", {
+		message: "No internal links found on the page",
+		links: listLinks(switcherLinks)
+	});
+	else if (!isLocaleInUrl || !pageLocale) emitCheck(emit, localizedLinksType, "warning", {
+		message: `The locale is not reflected in the URLs (routing: ${routing.strategy}). Each locale needs its own crawlable URL to be indexed.`,
+		links: listLinks(internalLinks)
+	});
+	else if (sameLocaleLinks.length === 0) emitCheck(emit, localizedLinksType, "warning", {
+		message: `None of the ${internalLinks.length} internal links points to the "${pageLocale}" version (routing: ${routing.strategy})`,
+		links: listLinks(internalLinks)
+	});
+	else emitCheck(emit, localizedLinksType, "success", {
+		message: `${sameLocaleLinks.length} of ${internalLinks.length} internal links point to the "${pageLocale}" version (routing: ${routing.strategy})`,
+		links: listLinks(sameLocaleLinks)
 	});
+	if (isLocaleInUrl && pageLocale && internalLinks.length > 0) {
+		const brokenLinks = [...otherLocaleLinks, ...unlocalizedLinks];
+		emitCheck(emit, urlCheckType("url_allAnchorsLocalized", targetUrl), brokenLinks.length === 0 ? "success" : "warning", brokenLinks.length === 0 ? `All ${internalLinks.length} internal links keep the "${pageLocale}" locale` : {
+			message: `${brokenLinks.length} internal links leave the "${pageLocale}" locale (${otherLocaleLinks.length} to another locale, ${unlocalizedLinks.length} without locale)`,
+			links: listLinks(brokenLinks)
+		});
+	}
+	if (routing.locales.length > 1) emitCheck(emit, urlCheckType("url_hasLangSelector", targetUrl), switcherLinks.length > 0 ? "success" : "warning", switcherLinks.length > 0 ? {
+		message: `${switcherLinks.length} crawlable links to other locale versions`,
+		links: listLinks(switcherLinks)
+	} : "No crawlable <a href> to the other locale versions: search engines only discover them through hreflang");
 };
+const getFilename = (url) => url.split("/").pop()?.split("?")[0] ?? url;
+const formatChunk = (chunk) => ({
+	filename: getFilename(chunk.url),
+	url: chunk.url,
+	fileSize: formatSize(chunk.fileSize),
+	totalLocaleSize: formatSize(chunk.totalLocaleSize),
+	usedLocaleSize: formatSize(chunk.usedLocaleSize),
+	unusedLocaleSize: formatSize(chunk.unusedLocaleSize),
+	dictionariesFound: chunk.dictionariesFound,
+	unusedPercent: `${chunk.unusedPercent}%`
+});
+/** Human-readable version of a {@link BundleContentAnalysis}, for display. */
+const formatBundleAnalysis = (analysis) => ({
+	currentLocale: analysis.currentLocale,
+	totalPageSize: formatSize(analysis.totalPageSize),
+	renderedContentSize: formatSize(analysis.renderedContentSize),
+	contentSize: formatSize(analysis.contentSize),
+	totalLocaleSize: formatSize(analysis.totalLocaleSize),
+	totalUnusedLocaleSize: formatSize(analysis.totalUnusedLocaleSize),
+	unusedPercentOfLocale: `${analysis.unusedPercentOfLocale}%`,
+	mainBundleChunks: analysis.mainBundleChunks.map(formatChunk),
+	lazyBundleChunks: analysis.lazyBundleChunks.map(formatChunk)
+});
 /**
-* Analyze the JavaScript bundles for unused locale content and emit the
-* corresponding event. Returns the analysis so callers can report on it.
+* `url_unusedBundleContent`: share of other-locale translations shipped in the
+* eagerly loaded bundles. Returns the raw analysis for reporting.
 */
-const checkBundleContent = (chunks, html, currentLocale, targetUrl, totalPageSize, events) => {
+const checkBundleContent = (chunks, html, currentLocale, targetUrl, totalPageSize, emit) => {
+	const type = urlCheckType("url_unusedBundleContent", targetUrl);
 	if (!currentLocale) {
-		events.push({
-			type: `url_unusedBundleContent\\${targetUrl}`,
-			status: "warning",
-			details: { warning: "Cannot analyse bundle content: page locale not detected" }
-		});
+		emitCheck(emit, type, "warning", "Cannot analyse bundle content: page locale not detected");
 		return;
 	}
 	const analysis = analyzeBundleContent(chunks, html, currentLocale, totalPageSize);
-	const mainBundleMaxUnused = analysis.mainBundleChunks.reduce((max, c) => Math.max(max, c.unusedPercent), 0);
-	const status = mainBundleMaxUnused === 0 ? "success" : mainBundleMaxUnused <= 30 ? "warning" : "error";
-	events.push({
-		type: `url_unusedBundleContent\\${targetUrl}`,
-		status,
-		details: { [status]: analysis }
-	});
+	const mainBundleMaxUnused = analysis.mainBundleChunks.reduce((max, chunk) => Math.max(max, chunk.unusedPercent), 0);
+	emitCheck(emit, type, mainBundleMaxUnused === 0 ? "success" : mainBundleMaxUnused <= 30 ? "warning" : "error", formatBundleAnalysis(analysis));
 	return analysis;
 };
-/** Fetch and check `robots.txt`, emitting robots-related events. */
-const checkRobots = async (origin, discoveredLocales, userAgent, events) => {
-	let robotsPresent = false;
-	let noLocalizedUrlsForgotten = true;
-	const errors = [];
-	try {
-		const response = await fetch(`${origin}/robots.txt`, { headers: { "User-Agent": userAgent } });
-		if (response.ok) {
-			robotsPresent = true;
-			const content = await response.text();
-			if (content && discoveredLocales.size > 0) {
-				const disallowedPaths = content.split("\n").map((line) => line.trim().toLowerCase()).filter((line) => line.startsWith("disallow:")).map((line) => line.slice(9).trim());
-				for (const locale of discoveredLocales) for (const path of disallowedPaths) if (path === `/${locale}` || path === `/${locale}/`) {
-					noLocalizedUrlsForgotten = false;
-					errors.push(`Locale path "${locale}" appears to be blocked in robots.txt: ${path}`);
-				}
-			}
-		}
-	} catch (error) {
-		errors.push(`Failed to fetch robots.txt: ${error instanceof Error ? error.message : "Unknown error"}`);
+/**
+* Fetch `robots.txt` and check that neither the site nor its localized URLs
+* are blocked for Googlebot.
+*
+* - `robots_robotsPresent`
+* - `robots_noLocalizedUrlsForgotten`
+*
+* @param localizedUrls - URLs of every locale version (hreflang alternates).
+* @returns The sitemaps declared in `robots.txt`.
+*/
+const checkRobots = async (origin, localizedUrls, fetchOptions, emit) => {
+	const response = await fetchText(`${origin}/robots.txt`, fetchOptions);
+	if (!response?.ok) {
+		emitCheck(emit, "robots_robotsPresent", "warning", response ? `No robots.txt found (HTTP ${response.status})` : "robots.txt is unreachable");
+		return [];
 	}
-	events.push({
-		type: "robots_robotsPresent",
-		status: robotsPresent ? "success" : "warning",
-		details: {
-			warning: robotsPresent ? void 0 : "No robots.txt found",
-			error: errors.length > 0 ? errors : void 0
-		}
+	const robots = parseRobots(response.text);
+	emitCheck(emit, "robots_robotsPresent", "success", {
+		disallow: robots.disallowedPaths,
+		sitemaps: robots.sitemapUrls
 	});
-	if (robotsPresent) events.push({
-		type: "robots_noLocalizedUrlsForgotten",
-		status: noLocalizedUrlsForgotten ? "success" : "error",
-		details: { error: noLocalizedUrlsForgotten ? void 0 : errors }
+	const blockedUrls = [origin, ...localizedUrls].filter((url) => {
+		const parsedUrl = parseUrl(url);
+		return parsedUrl?.origin === origin && !isPathAllowedByRobots(`${parsedUrl.pathname}${parsedUrl.search}`, robots);
 	});
+	const isSiteBlocked = !isPathAllowedByRobots("/", robots);
+	emitCheck(emit, "robots_noLocalizedUrlsForgotten", blockedUrls.length === 0 ? "success" : "error", blockedUrls.length === 0 ? true : isSiteBlocked ? "robots.txt blocks the whole site for Googlebot (Disallow: /)" : {
+		message: "Localized URLs blocked by robots.txt",
+		urls: [...new Set(blockedUrls)]
+	});
+	return robots.sitemapUrls;
 };
-/** Fetch and check `sitemap.xml`, emitting sitemap-related events. */
-const checkSitemap = async (origin, discoveredLocales, userAgent, events) => {
-	let sitemapPresent = false;
-	let hasXDefault = false;
+/**
+* Read the sitemaps (declared in `robots.txt`, else the default locations,
+* following sitemap indexes) and check their locale coverage.
+*
+* - `sitemap_sitemapPresent`
+* - `sitemap_noLocalizedUrlsForgotten`: every locale is listed, and entries
+*   declaring alternates declare all of them
+* - `sitemap_hasAlternates` / `sitemap_hasXDefault`
+*/
+const checkSitemap = async (origin, declaredSitemapUrls, routing, fetchOptions, emit) => {
+	const { fetchedSitemapUrls, entries, isTruncated } = await collectSitemapEntries(declaredSitemapUrls.length > 0 ? declaredSitemapUrls : getDefaultSitemapUrls(origin), fetchOptions);
+	if (fetchedSitemapUrls.length === 0) {
+		emitCheck(emit, "sitemap_sitemapPresent", "warning", declaredSitemapUrls.length > 0 ? `Sitemaps declared in robots.txt are unreachable: ${declaredSitemapUrls.join(", ")}` : "No sitemap found (robots.txt Sitemap directive, /sitemap.xml, /sitemap_index.xml)");
+		return;
+	}
+	emitCheck(emit, "sitemap_sitemapPresent", "success", {
+		sitemaps: fetchedSitemapUrls,
+		urlCount: entries.length,
+		isTruncated
+	});
+	const knownLocales = routing.locales;
+	const foundLanguages = /* @__PURE__ */ new Set();
+	const entriesWithoutSelfReference = [];
+	const relativeAlternates = [];
+	let partiallyTranslatedCount = 0;
 	let hasAlternates = false;
-	let noLocalizedUrlsForgotten = true;
-	const errors = [];
-	try {
-		const response = await fetch(`${origin}/sitemap.xml`, { headers: { "User-Agent": userAgent } });
-		if (response.ok) {
-			sitemapPresent = true;
-			const content = await response.text();
-			const hreflangs = (content.match(/hreflang\s*=\s*"([^"]+)"/gi) ?? []).map((m) => m.replace(/hreflang\s*=\s*"/i, "").replace(/"$/, ""));
-			hasAlternates = hreflangs.length > 0;
-			hasXDefault = hreflangs.includes("x-default");
-			if (discoveredLocales.size > 0) {
-				const urlBlocks = content.match(/<url\b[\s\S]*?<\/url>/gi) ?? [];
-				const allFoundLocales = /* @__PURE__ */ new Set();
-				let anyUrlMissingLocale = false;
-				for (const block of urlBlocks) {
-					const localesInUrl = /* @__PURE__ */ new Set();
-					for (const hreflang of block.match(/hreflang\s*=\s*"([^"]+)"/gi) ?? []) {
-						const value = hreflang.replace(/hreflang\s*=\s*"/i, "").replace(/"$/, "");
-						if (value !== "x-default") {
-							localesInUrl.add(value);
-							allFoundLocales.add(value);
-						}
-					}
-					const loc = block.match(/<loc>([\s\S]*?)<\/loc>/i)?.[1]?.trim();
-					if (loc) try {
-						const firstSegment = new URL(loc).pathname.split("/").filter(Boolean)[0];
-						if (firstSegment && discoveredLocales.has(firstSegment)) {
-							localesInUrl.add(firstSegment);
-							allFoundLocales.add(firstSegment);
-						}
-					} catch {}
-					const missing = [...discoveredLocales].filter((locale) => !localesInUrl.has(locale));
-					if (missing.length > 0 && missing.length < discoveredLocales.size) anyUrlMissingLocale = true;
-				}
-				const completelyMissing = [...discoveredLocales].filter((locale) => !allFoundLocales.has(locale));
-				if (anyUrlMissingLocale || completelyMissing.length > 0) {
-					noLocalizedUrlsForgotten = false;
-					if (completelyMissing.length > 0) errors.push(`The following locales are completely missing from the sitemap: ${completelyMissing.join(", ")}`);
-				}
+	let hasXDefault = false;
+	for (const { loc, alternates } of entries) {
+		const locLocale = getUrlLocale(loc, routing);
+		if (locLocale) foundLanguages.add(getLanguageCode(locLocale));
+		if (alternates.length === 0) continue;
+		hasAlternates = true;
+		const entryLanguages = /* @__PURE__ */ new Set();
+		for (const { hreflang, href } of alternates) {
+			if (!isAbsoluteUrl(href)) relativeAlternates.push(`${loc}: ${hreflang} → ${href}`);
+			if (hreflang.toLowerCase() === "x-default") {
+				hasXDefault = true;
+				continue;
 			}
+			entryLanguages.add(getLanguageCode(hreflang));
+			foundLanguages.add(getLanguageCode(hreflang));
 		}
-	} catch (error) {
-		errors.push(`Failed to fetch sitemap.xml: ${error instanceof Error ? error.message : "Unknown error"}`);
+		const normalizedLoc = normalizeUrl(loc);
+		if (!alternates.some(({ href }) => normalizeUrl(href) === normalizedLoc)) entriesWithoutSelfReference.push(loc);
+		if (entryLanguages.size < knownLocales.length) partiallyTranslatedCount++;
 	}
-	events.push({
-		type: "sitemap_sitemapPresent",
-		status: sitemapPresent ? "success" : "warning",
-		details: {
-			warning: sitemapPresent ? void 0 : "No sitemap.xml found",
-			error: errors.length > 0 ? errors : void 0
-		}
-	});
-	if (sitemapPresent) {
-		events.push({
-			type: "sitemap_noLocalizedUrlsForgotten",
-			status: noLocalizedUrlsForgotten ? "success" : "warning",
-			details: { warning: noLocalizedUrlsForgotten ? void 0 : errors }
-		});
-		events.push({
-			type: "sitemap_hasXDefault",
-			status: hasXDefault ? "success" : "warning",
-			details: { warning: hasXDefault ? void 0 : "No x-default hreflang in sitemap" }
-		});
-		events.push({
-			type: "sitemap_hasAlternates",
-			status: hasAlternates ? "success" : "warning",
-			details: { warning: hasAlternates ? void 0 : "No alternate language links found in sitemap" }
-		});
+	const isSingleOriginRouting = routing.strategy !== "subdomain" && routing.strategy !== "domain";
+	if (knownLocales.length > 1) {
+		const missingLocales = isSingleOriginRouting ? knownLocales.filter((locale) => !foundLanguages.has(getLanguageCode(locale))) : [];
+		const issues = [...missingLocales.length > 0 ? [`Locales missing from the sitemap: ${missingLocales.join(", ")}`] : [], ...entriesWithoutSelfReference.slice(0, MAX_LISTED_LINKS).map((loc) => `${loc} is not listed among its own alternates`)];
+		emitCheck(emit, "sitemap_noLocalizedUrlsForgotten", issues.length === 0 ? "success" : "warning", issues.length === 0 ? {
+			message: `Every locale (${knownLocales.join(", ")}) is listed`,
+			partiallyTranslatedUrlCount: partiallyTranslatedCount
+		} : issues);
 	}
+	if (!hasAlternates) emitCheck(emit, "sitemap_hasAlternates", "warning", "No alternate language links found in the sitemap");
+	else if (relativeAlternates.length > 0) emitCheck(emit, "sitemap_hasAlternates", "error", {
+		message: `${relativeAlternates.length} sitemap hreflang alternates are not absolute URLs (https://…): search engines ignore them`,
+		alternates: relativeAlternates.slice(0, MAX_LISTED_LINKS)
+	});
+	else emitCheck(emit, "sitemap_hasAlternates", "success", true);
+	emitCheck(emit, "sitemap_hasXDefault", hasXDefault ? "success" : "warning", hasXDefault ? true : "No x-default hreflang in the sitemap");
 };
 
 //#endregion
-export { checkBundleContent, checkCanonical, checkHtmlAttributes, checkLinguisticStructure, checkRobots, checkSitemap, checkUrlStructure, formatSize };
+export { checkBundleContent, checkCanonical, checkHreflang, checkHreflangReciprocity, checkHtmlDir, checkHtmlLang, checkInternalLinks, checkLocaleConsistency, checkOgLocale, checkRobots, checkSitemap, checkXDefault, formatBundleAnalysis, formatSize };
 //# sourceMappingURL=checks.mjs.map