@goflag/cli 0.2.4 → 0.2.7

package/README.md

@@ -16,9 +16,14 @@ on the site. A human cannot check those on 400 pages. That is the whole job.
 ## What it checks
 
 - **Broken links** — scrapes every crawled page, dedupes targets globally (a footer link on 500 pages is probed once), and checks each with `HEAD`→`GET` fallback, redirect-chain/loop detection, soft-404 and anti-bot (403/429) triage. Broken links are mapped back to the pages that reference them.
-- **Missing translation pages** — builds a `route × locale` matrix from the crawl and flags every route that exists in one locale but is missing in another, plus hreflang reciprocity gaps (`A → B` with no `B → A`), missing `x-default`, and invalid locale tags.
+- **Missing translation pages** — builds a `route × locale` matrix and flags every route that exists in one locale but is missing in another, plus hreflang reciprocity gaps (`A → B` with no `B → A`), missing `x-default`, and locale tags naming a language, script or region that does not exist. Rows are keyed by pathname, unless your sitemap declares its translation clusters with `xhtml:link` — then those declarations decide which URLs are one page, whatever their slugs, and the run reports `diagnostics.declaredClusters`.
 - **robots.txt policy** — flags a site that forbids crawling while its pages ask to be indexed. The two declarations cannot both hold, and robots.txt wins, so the meta tag is never even read.
 - **SEO metadata** — lints each page's `<head>` for the handful of mistakes that actually hurt in search and social and are invisible in a browser: missing/oversized `<title>` and description, missing/relative canonical, missing `og:title`/`og:description`/`og:image`, missing viewport, and contradictory `robots`/`googlebot`/`X-Robots-Tag` directives.
+- **Unreachable pages** — a page the crawl reached that answered non-2xx, or that never answered at all (timeout, reset, DNS failure — recorded as `status: 0`), is reported in `unreachablePages`. goflag asks a second time, from the back of the queue, before calling a page unreachable. Each one is an `error`-severity finding: it turns the verdict red, counts toward `--max-debt`, and fails the build even under `--fail-on error`. A page that silently dropped out of the audited set is what poisons a baseline, so it is reported rather than warned about.
+
+**Which pages get audited.** When goflag finds a sitemap it does not audit every URL in it. It groups URLs that share a path shape — and therefore a template — into families, audits every page that stands alone, and samples three pages per family. A cap answers "how many" and never "which": on a site of thousands of pages built from thirty templates, the first 200 pages a crawl reaches are four templates out of thirty.
+
+The trade is stated in every report rather than hidden. Template rules (`canonical.*`, `hreflang.*`, `og.image.missing`) are conclusive on a sampled family; copy rules (`title.length`, `description.length`), broken links and the translation matrix are only conclusive on the pages that were drawn. The terminal prints a `COVERAGE` line, and `diagnostics.coverage` carries `mode`, `considered`, `selected` and every sampled family with its ratio. Pass `--coverage all` to audit what the sitemap lists in order, up to `--max-pages`, which is the pre-0.2.3 behaviour.
 
 Pages that declare a `<link rel="canonical">` pointing at another crawled page are excluded from the checks — the site has said they are duplicates, so linting them would multiply every finding by the number of filtered variants. The count is reported as `diagnostics.duplicatePages`.
 
@@ -125,16 +130,57 @@ npx @goflag/cli https://example.com --report report.json      # write JSON to a
 
 The terminal view is just a render of that JSON.
 
+### The catalogue is data too
+
+```sh
+npx @goflag/cli rules > rules.json
+```
+
+`rules` answers a question about goflag rather than about a site: no URL, no
+crawl, no network. Every entry carries its scope, severity and summary; the
+eleven page rules and four prose rules also carry a rigor, the documents they
+cite and — where a remedy is a line of code — a fix snippet. The three site
+rules carry none of those three: `SiteRule` has no rigor field yet, and the
+catalogue emits `rigor: null` with an empty `sources` rather than inventing an
+authority nobody assigned. Write your consumer against that. The same document
+ships inside the package as `rules.json`, if you would rather read it than run
+anything.
+
+It deliberately omits the message a finding prints — that is built at audit time
+from what the page actually says, so a static copy would be a sample rather than
+a fact, and a sample presented as the truth is how this project's own
+documentation site came to quote a message the engine had stopped printing.
+
 ### Options
 
 ```
 --json                 Print the JSON report to stdout (nothing else).
+--summary, -s          Roll findings up (dedup by link/rule/code). Pairs with
+                       --json for a compact payload; --report always writes
+                       the full report regardless.
 --report <file>        Write the JSON report to <file>.
---depth <n>            Crawl depth (0 = entry page only). Default: 2.
---max-pages <n>        Hard cap on pages crawled. Default: 200.
+--depth <n>            How far to follow links out of each page (0 = follow
+                       none). Sitemap URLs are seeded regardless, so --depth 0
+                       alone is not "entry page only" — add --no-sitemap.
+                       Default: 2.
+--max-pages <n>        Page budget for the crawl. Default: 200. A hard cap
+                       under --coverage all; under structural coverage the
+                       selection wins and the budget is max(<n>, selected + 5),
+                       so a lower value cannot cut the run short.
+--coverage <mode>      How pages are chosen: "structural" (default when a
+                       sitemap is found) keeps every standalone page and
+                       samples three pages per family of template-generated
+                       pages; "all" audits what the sitemap lists, in order,
+                       up to --max-pages.
 --include <glob>       Only crawl paths matching <glob> (repeatable).
 --exclude <glob>       Skip paths matching <glob> (repeatable).
 --locales <list>       Comma-separated locales the site serves ("fr,en,pt-br").
+                       Unioned with the prefixes your sitemap shows, never
+                       substituted for them, so a locale the sitemap serves
+                       stays on the axis whether or not you list it. Also what
+                       folds /en/… and /fr/… into one route family for
+                       structural coverage — pass it on any locale-prefixed
+                       site.
 --ignore-holes <glob>  Route deliberately not translated everywhere
                        (repeatable).
 --no-sitemap           Do not discover the sitemap; crawl from <url> only.
@@ -160,7 +206,11 @@ The terminal view is just a render of that JSON.
 --no-external          Do not probe off-origin (external) links.
 --static               Static HTML only; never launch headless Chromium.
 --allow-insecure-tls   Accept self-signed / invalid TLS (localhost, tunnels).
---timeout <ms>         Per-request timeout in ms. Default: 8000.
+--timeout <ms>         Per-request timeout in ms, for page fetches and link
+                       probes alike. Unset, the defaults differ: 8000 for link
+                       probes, 15000 for page fetches.
+--verbose, -V          Log every page as it is analyzed.
+--quiet, -q            Suppress the live progress output.
 --no-color             Disable coloured output.
 -h, --help             Show help.
 -v, --version          Show the version.
@@ -351,9 +401,16 @@ goflag https://example.com --locales fr,en,pt-br
 
 When a site publishes no usable sitemap and you pass no `--locales`, goflag
 does **not** guess the locale axis — it reports the prefixes it saw with the
-evidence for each and turns the i18n checks off. Guessing from path shape alone
-once turned `/cv` (a CV page served in French) into a locale, because `cv` is a
-registered ISO 639-1 code, and produced 31 findings that were never real.
+evidence for each and turns the axis-dependent checks off (holes,
+`hreflang.missing`, `hreflang.sitemap-mismatch`; the reciprocity checks read the
+markup and keep running). Guessing from path shape alone once turned `/cv` (a CV
+page served in French) into a locale, because `cv` is a registered ISO 639-1
+code, and produced 31 findings that were never real.
+
+Pass `--locales` even when the sitemap is fine. It is the axis goflag folds when
+it groups URLs into route families, so without it a site with many top-level
+sections under `/en` can have those sections sampled as one family instead of
+audited.
 
 Some pages are meant to exist in one locale and not another — a
 jurisdiction-specific legal notice, a post written for one market. A site has
@@ -398,7 +455,7 @@ Three rules, whichever you use:
 stages: [build, deploy, audit]
 
 variables:
-  GOFLAG_VERSION: "0.1.4"
+  GOFLAG_VERSION: "0.2.7"
 
 # Before the merge: build the branch, let goflag boot it, audit that.
 seo:mr:
@@ -412,6 +469,7 @@ seo:mr:
     - npx --yes "@goflag/cli@$GOFLAG_VERSION" http://localhost:3000
       --start "pnpm start" --static --no-external
       --baseline .goflag/baseline.json --regressions-only --max-debt 41
+      --report goflag-report.json
   artifacts:
     when: always
     paths: [goflag-report.json]
@@ -449,9 +507,10 @@ jobs:
       - run: corepack enable && pnpm install --frozen-lockfile
       - run: pnpm build
       - run: |
-          npx --yes @goflag/cli@0.1.4 http://localhost:3000 \
+          npx --yes @goflag/cli@0.2.7 http://localhost:3000 \
             --start "pnpm start" --static --no-external \
-            --baseline .goflag/baseline.json --regressions-only --max-debt 41
+            --baseline .goflag/baseline.json --regressions-only --max-debt 41 \
+            --report goflag-report.json
       - uses: actions/upload-artifact@v4
         if: always()
         with:
@@ -484,7 +543,8 @@ you what it accepted, and that number belongs in the commit message.
 import { runAudit } from "@goflag/cli";
 
 const report = await runAudit("https://example.com", { depth: 2 });
-console.log(report.summary); // { brokenLinks, missingTranslations, seoIssues, verdict }
+console.log(report.summary);
+// { brokenLinks, missingTranslations, seoIssues, siteIssues, unreachablePages, verdict }
 ```
 
 `runAudit` returns the same `GoflagReport` object the CLI emits.
@@ -543,9 +603,11 @@ pnpm typecheck                 # tsc --noEmit
 pnpm format                    # prettier
 ```
 
-`lint`, `format` and `format:check` run once over the whole repository; the
-rest fan out across workspace packages with `pnpm -r`. To work on one package,
-filter: `pnpm --filter @goflag/cli test`.
+`format` and `format:check` run once over the whole repository. `lint` runs
+eslint once at the root and then fans out to any package that defines its own
+`lint` script — `apps/website` does, with the Next config — and the rest fan out
+across workspace packages with `pnpm -r`. To work on one package, filter:
+`pnpm --filter @goflag/cli test`.
 
 The engine is framework-agnostic and lives in [`packages/cli/src/lib/core/`](packages/cli/src/lib/core) (crawl, fetch/extract, link audit, i18n) and [`packages/cli/src/lib/rules/`](packages/cli/src/lib/rules) (SEO checks). The CLI shell — orchestration, the `GoflagReport` schema, and rendering — lives in [`packages/cli/src/report/`](packages/cli/src/report) and [`packages/cli/src/cli.ts`](packages/cli/src/cli.ts).
 

package/dist/{chunk-TVJVVSLV.js → chunk-UOKYUKHQ.js}

@@ -970,7 +970,8 @@ async function inspect(url, options = {}) {
       extractor: {
         mode: "static",
         escalated: false,
-        escalationReason: `would-have-escalated (${heuristic.reason}) but ${err.message}`
+        escalationReason: heuristic.reason,
+        escalationBlocked: err.message
       },
       html: { static: staticBody },
       probes: probes2
@@ -1115,6 +1116,7 @@ function push(out, seen, href, source) {
 }
 
 // src/lib/core/crawl.ts
+var MAX_ATTEMPTS = 2;
 async function crawl(options) {
   const depthLimit = options.depth ?? 1;
   const concurrency = Math.max(1, options.concurrency ?? 4);
@@ -1128,6 +1130,7 @@ async function crawl(options) {
       pages: [],
       visited: [],
       errors: [{ url: options.entryUrl, message: "entry URL is not a valid http(s) URL" }],
+      recovered: [],
       truncated: false
     };
   }
@@ -1143,7 +1146,9 @@ async function crawl(options) {
   }
   const pages = [];
   const errors = [];
+  const recovered = [];
   let truncated = false;
+  const seenFinal = /* @__PURE__ */ new Set();
   while (queue.length > 0) {
     if (options.inspectOptions?.signal?.aborted) break;
     const wave = queue.splice(0, concurrency);
@@ -1162,9 +1167,18 @@ async function crawl(options) {
     const results = await Promise.all(inspections);
     for (const result of results) {
       if (result.kind === "err") {
+        const attempt = (result.item.attempt ?? 0) + 1;
+        if (attempt < MAX_ATTEMPTS) {
+          queue.push({ ...result.item, attempt });
+          continue;
+        }
         errors.push({ url: result.item.url, message: result.error });
         continue;
       }
+      if (result.item.attempt) recovered.push(result.item.url);
+      const finalUrl = canonicaliseUrl(result.page.fetch.finalUrl) ?? result.page.fetch.finalUrl;
+      if (seenFinal.has(finalUrl)) continue;
+      seenFinal.add(finalUrl);
       pages.push(result.page);
       if (options.onPage) {
         options.onPage(result.page, { visited: pages.length, queued: queue.length });
@@ -1194,6 +1208,7 @@ async function crawl(options) {
     pages,
     visited: [...visitedSet],
     errors,
+    recovered,
     truncated
   };
 }
@@ -1780,17 +1795,60 @@ function sortIssues(issues) {
   });
 }
 
-// src/lib/core/i18n.ts
-var BCP47_LOOSE = /^[a-z]{2,3}(-[a-z]{2}|-\d{3})?$/i;
-function localeIdentity(tag) {
-  return tag.trim().toLowerCase();
-}
+// src/lib/core/bcp47.ts
+var languageNames = new Intl.DisplayNames(["en"], { type: "language", fallback: "none" });
+var regionNames = new Intl.DisplayNames(["en"], { type: "region", fallback: "none" });
+var scriptNames = new Intl.DisplayNames(["en"], { type: "script", fallback: "none" });
+var NOT_AN_AUDIENCE_REGION = /* @__PURE__ */ new Set(["ZZ", "XA", "XB"]);
+var NOT_AN_AUDIENCE_LANGUAGE = /* @__PURE__ */ new Set(["mul", "zxx", "und", "mis"]);
+var NOT_A_SCRIPT = /* @__PURE__ */ new Set(["Zzzz"]);
+var ICU_KNOWS_LANGUAGES = languageNames.of("fr") !== void 0 && languageNames.of("qq") === void 0 && regionNames.of("BR") !== void 0;
+var ICU_UNAVAILABLE_WARNING = "This Node build cannot tell a real language tag from an invented one (small-icu). hreflang tags were checked for shape only, so `locale.invalid` may have missed tags that do not exist.";
+var BCP47_SHAPE = /^[a-z]{2,3}(-[a-z]{2}|-\d{3})?$/i;
 function looksLikeLocaleSegment(segment) {
-  return BCP47_LOOSE.test(segment);
+  return BCP47_SHAPE.test(segment);
 }
 function isValidLocale(tag) {
   if (tag === "x-default") return true;
-  return BCP47_LOOSE.test(tag);
+  if (!ICU_KNOWS_LANGUAGES) return BCP47_SHAPE.test(tag);
+  let canonical;
+  try {
+    canonical = Intl.getCanonicalLocales(tag)[0] ?? "";
+  } catch {
+    return false;
+  }
+  if (!canonical) return false;
+  let parts;
+  try {
+    parts = new Intl.Locale(canonical);
+  } catch {
+    return false;
+  }
+  const language = (parts.language ?? "").toLowerCase();
+  if (!language) return false;
+  if (NOT_AN_AUDIENCE_LANGUAGE.has(language)) return false;
+  if (languageNames.of(language) === void 0) return false;
+  if (parts.script) {
+    if (NOT_A_SCRIPT.has(parts.script)) return false;
+    if (scriptNames.of(parts.script) === void 0) return false;
+  }
+  if (parts.region) {
+    if (NOT_AN_AUDIENCE_REGION.has(parts.region)) return false;
+    if (regionNames.of(parts.region) === void 0) return false;
+  }
+  return true;
+}
+function isKnownLanguageTag(tag) {
+  const primary = (tag.toLowerCase().split("-")[0] ?? "").trim();
+  if (!primary) return false;
+  if (NOT_AN_AUDIENCE_LANGUAGE.has(primary)) return false;
+  if (!ICU_KNOWS_LANGUAGES) return BCP47_SHAPE.test(primary);
+  return languageNames.of(primary) !== void 0;
+}
+
+// src/lib/core/i18n.ts
+function localeIdentity(tag) {
+  return tag.trim().toLowerCase();
 }
 function buildI18nMatrix(pages, options = {}) {
   const inspectedByUrl = /* @__PURE__ */ new Map();
@@ -1802,6 +1860,9 @@ function buildI18nMatrix(pages, options = {}) {
     const tag = locale.trim().toLowerCase();
     if (tag) locales.add(tag);
   }
+  function rowOf(url, pathnameRoute) {
+    return options.clusterRouteOf?.(url) ?? pathnameRoute;
+  }
   function record(route, locale, url) {
     routes.add(route);
     locales.add(locale);
@@ -1817,7 +1878,7 @@ function buildI18nMatrix(pages, options = {}) {
   for (const page of pages) {
     const url = new URL(page.fetch.finalUrl);
     const { route: selfRoute, locale: selfLocale } = splitRoute(url.pathname);
-    record(selfRoute, selfLocale, page.fetch.finalUrl);
+    record(rowOf(page.fetch.finalUrl, selfRoute), selfLocale, page.fetch.finalUrl);
     for (const alt of page.links.alternates) {
       let altUrl;
       try {
@@ -1827,7 +1888,7 @@ function buildI18nMatrix(pages, options = {}) {
       }
       const { route } = splitRoute(altUrl.pathname);
       const locale = alt.isXDefault ? "x-default" : localeIdentity(alt.hreflang);
-      record(route || selfRoute, locale, altUrl.toString());
+      record(rowOf(altUrl.toString(), route || selfRoute), locale, altUrl.toString());
     }
   }
   for (const declared of options.declaredUrls ?? []) {
@@ -1838,7 +1899,7 @@ function buildI18nMatrix(pages, options = {}) {
       continue;
     }
     const { route, locale } = splitRoute(url.pathname);
-    record(route, locale, url.toString());
+    record(rowOf(url.toString(), route), locale, url.toString());
   }
   const sortedLocales = sortLocales([...locales]);
   const sortedRoutes = [...routes].sort((a, b) => a.localeCompare(b));
@@ -2155,13 +2216,6 @@ function sortSiteIssues(drafts) {
 }
 
 // src/lib/core/locales.ts
-var ISO_639_1 = new Set(
-  "aa ab ae af ak am an ar as av ay az ba be bg bh bi bm bn bo br bs ca ce ch co cr cs cu cv cy da de dv dz ee el en eo es et eu fa ff fi fj fo fr fy ga gd gl gn gu gv ha he hi ho hr ht hu hy hz ia id ie ig ii ik io is it iu ja jv ka kg ki kj kk kl km kn ko kr ks ku kv kw ky la lb lg li ln lo lt lu lv mg mh mi mk ml mn mr ms mt my na nb nd ne ng nl nn no nr nv ny oc oj om or os pa pi pl ps pt qu rm rn ro ru rw sa sc sd se sg si sk sl sm sn so sq sr ss st su sv sw ta te tg th ti tk tl tn to tr ts tt tw ty ug uk ur uz ve vi vo wa wo xh yi yo za zh zu".split(" ")
-);
-function isKnownLanguageTag(tag) {
-  const primary = tag.toLowerCase().split("-")[0] ?? "";
-  return ISO_639_1.has(primary);
-}
 function localePrefixOf(url) {
   let pathname;
   try {
@@ -2242,6 +2296,26 @@ import { gunzipSync } from "zlib";
 
 // src/lib/core/sitemap/parse.ts
 import * as cheerio2 from "cheerio";
+function alternatesOf(node) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  node.children().each((_, el) => {
+    const tag = "tagName" in el ? el.tagName ?? "" : "";
+    if (tag.split(":").pop()?.toLowerCase() !== "link") return;
+    const attrs = "attribs" in el ? el.attribs : void 0;
+    if (!attrs) return;
+    const rel = (attrs.rel ?? "alternate").trim().toLowerCase();
+    if (rel !== "alternate") return;
+    const hreflang = (attrs.hreflang ?? "").trim();
+    const href = (attrs.href ?? "").trim();
+    if (!hreflang || !href) return;
+    const key = `${hreflang.toLowerCase()}\0${href}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ hreflang, href });
+  });
+  return out;
+}
 function parseSitemap(body) {
   const trimmed = body.trim();
   if (trimmed.length === 0) {
@@ -2280,6 +2354,8 @@ function parseSitemap(body) {
       if (changefreq) entry.changefreq = changefreq;
       const priority = node.find("priority").first().text().trim();
       if (priority) entry.priority = priority;
+      const alternates = alternatesOf(node);
+      if (alternates.length > 0) entry.alternates = alternates;
       urls.push(entry);
     });
     return { kind: "urlset", wellFormed: true, urls };
@@ -2499,6 +2575,54 @@ function relaxTlsIfRequested2(enabled) {
   };
 }
 
+// src/lib/core/clusters.ts
+function normalise(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  url.hash = "";
+  const path = url.pathname.length > 1 ? url.pathname.replace(/\/+$/, "") : url.pathname;
+  return `${url.origin}${path}${url.search}`;
+}
+var X_DEFAULT = "x-default";
+function buildClusterIndex(entries) {
+  const routeByUrl = /* @__PURE__ */ new Map();
+  const conflicts = [];
+  const anchors = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const alternates = entry.alternates;
+    if (!alternates || alternates.length === 0) continue;
+    const xDefault = alternates.find((a) => a.hreflang.trim().toLowerCase() === X_DEFAULT);
+    if (!xDefault) continue;
+    const anchorUrl = normalise(xDefault.href);
+    if (!anchorUrl) continue;
+    const { route: anchorRoute } = splitRoute(new URL(anchorUrl).pathname);
+    anchors.add(anchorRoute);
+    const members = [entry.loc, ...alternates.map((a) => a.href)];
+    for (const member of members) {
+      const url = normalise(member);
+      if (!url) continue;
+      const existing = routeByUrl.get(url);
+      if (existing === void 0) {
+        routeByUrl.set(url, anchorRoute);
+        continue;
+      }
+      if (existing !== anchorRoute && !conflicts.includes(url)) conflicts.push(url);
+    }
+  }
+  return {
+    routeOf: (url) => {
+      const key = normalise(url);
+      return key === null ? void 0 : routeByUrl.get(key);
+    },
+    size: anchors.size,
+    conflicts
+  };
+}
+
 // src/lib/core/coverage.ts
 var DEFAULT_PER_FAMILY = 3;
 var DEFAULT_THRESHOLD = 8;
@@ -3431,6 +3555,11 @@ function localeOfUrl(url) {
   }
   return null;
 }
+function blockedEscalationWarning(pages) {
+  const blocked = pages.filter((p) => p.extractor.escalationBlocked);
+  if (blocked.length === 0) return null;
+  return `${blocked.length} page(s) looked client-rendered and were judged on their static HTML, because the browser could not be started: ${blocked[0].extractor.escalationBlocked} Their metadata findings may be phantoms \u2014 install Playwright and Chromium, or pass --static to say the static HTML is what you meant to judge.`;
+}
 function deriveTranslationHoles(matrix, ignoreRoutes = []) {
   const realLocales = matrix.locales.filter((l) => l !== "x-default");
   if (realLocales.length < 2) return [];
@@ -3497,6 +3626,7 @@ async function runAudit(inputUrl, options = {}) {
     crawlFallback: false
   }).catch(() => void 0);
   const allSitemapUrls = (discovery?.urls ?? []).map((u) => u.loc);
+  const clusters = buildClusterIndex(discovery?.urls ?? []);
   const coverageMode = options.coverage ?? (allSitemapUrls.length > 0 ? "structural" : "all");
   const selection = coverageMode === "structural" && allSitemapUrls.length > 0 ? selectByStructure(allSitemapUrls, { locales: options.locales }) : void 0;
   const sitemapUrls = selection?.urls ?? allSitemapUrls;
@@ -3529,6 +3659,13 @@ async function runAudit(inputUrl, options = {}) {
   });
   const pages = crawlResult.pages;
   const warnings = crawlResult.errors.map((e) => `crawl: ${e.url} \u2014 ${e.message}`);
+  if (crawlResult.recovered.length > 0) {
+    warnings.push(
+      `${crawlResult.recovered.length} page(s) failed once and answered on retry: ${crawlResult.recovered.slice(0, 3).join(", ")}${crawlResult.recovered.length > 3 ? `, +${crawlResult.recovered.length - 3} more` : ""}.`
+    );
+  }
+  const escalationWarning = blockedEscalationWarning(pages);
+  if (escalationWarning) warnings.push(escalationWarning);
   const okPages = pages.filter((p) => isOkStatus(p.fetch.status));
   const documents = okPages.filter(isHtmlPage);
   const { kept: htmlPages, dropped: duplicatePages } = dropCanonicalDuplicates(documents);
@@ -3591,10 +3728,17 @@ async function runAudit(inputUrl, options = {}) {
       suggestion ? `No sitemap and no --locales: i18n checks are off. Locale-looking prefixes found \u2014 re-run with \`--locales ${suggestion}\` to enable them.` : `No sitemap and no --locales: i18n checks are off. Prefixes seen (${localeAxis.candidates.map((c) => c.tag).join(", ")}) do not look like locales; pass --locales if any of them is one.`
     );
   }
+  if (!ICU_KNOWS_LANGUAGES) warnings.push(ICU_UNAVAILABLE_WARNING);
   const matrix = buildI18nMatrix(htmlPages, {
     declaredUrls: sitemapUrls,
-    locales: localeAxis.locales
+    locales: localeAxis.locales,
+    clusterRouteOf: clusters.routeOf
   });
+  if (clusters.conflicts.length > 0) {
+    warnings.push(
+      `${clusters.conflicts.length} URL(s) are declared in two different hreflang clusters by the sitemap; the first declaration was kept: ${clusters.conflicts.slice(0, 3).join(", ")}${clusters.conflicts.length > 3 ? `, +${clusters.conflicts.length - 3} more` : ""}.`
+    );
+  }
   const holes = localeAxis.multilingual ? deriveTranslationHoles(matrix, options.ignoreHoles) : [];
   const ignoredHoles = localeAxis.multilingual && (options.ignoreHoles?.length ?? 0) > 0 ? deriveTranslationHoles(matrix).length - holes.length : 0;
   const reciprocity = reciprocityIssues(htmlPages).map((issue) => ({
@@ -3739,6 +3883,15 @@ async function runAudit(inputUrl, options = {}) {
       },
       ...ignoredHoles > 0 ? { ignoredHoles } : {},
       ...duplicatePages > 0 ? { duplicatePages } : {},
+      // Only when the site declared clusters. A merge that changes which rows
+      // exist must be visible: the alternative is a hole count that moved for
+      // a reason nothing in the report explains.
+      ...clusters.size > 0 ? {
+        declaredClusters: {
+          count: clusters.size,
+          ...clusters.conflicts.length > 0 ? { conflicts: clusters.conflicts.length } : {}
+        }
+      } : {},
       ...discovery ? {
         sitemap: {
           found: discovery.diagnostics.found,
@@ -4395,9 +4548,12 @@ var Logger = class {
 };
 
 export {
+  RULES,
+  SITE_RULES,
   DEFAULT_PROFILE,
   PROFILES,
   PROFILE_NAMES,
+  PROSE_RULES,
   routeKey,
   targetKey,
   fingerprint,
@@ -4410,4 +4566,4 @@ export {
   summarize,
   Logger
 };
-//# sourceMappingURL=chunk-TVJVVSLV.js.map
+//# sourceMappingURL=chunk-UOKYUKHQ.js.map