@goflag/cli 0.2.10 → 0.2.11

package/dist/{chunk-DKGBLJ4H.js → chunk-CWEJ6EXT.js}

@@ -2741,6 +2741,7 @@ function rowOf(site, url, pathname) {
 }
 function sitemapLocalesByRoute(site) {
   const byRoute = /* @__PURE__ */ new Map();
+  const axis = new Set(site.localeAxis.locales.map((l) => l.toLowerCase()));
   for (const entry of site.discovery?.urls ?? []) {
     let pathname;
     try {
@@ -2750,6 +2751,7 @@ function sitemapLocalesByRoute(site) {
     }
     const { locale } = splitRoute(pathname);
     if (locale === "x-default") continue;
+    if (!axis.has(locale.toLowerCase())) continue;
     const route = rowOf(site, entry.loc, pathname);
     const set = byRoute.get(route) ?? /* @__PURE__ */ new Set();
     set.add(locale.toLowerCase());
@@ -2764,6 +2766,8 @@ var hreflangMissing = {
   id: "hreflang.missing",
   severity: "error",
   summary: "Pages on a multilingual site must advertise their locale alternates",
+  rigor: "vendor-spec",
+  sources: ["google-hreflang", "whatwg-html-link-types"],
   appliesTo: isMultilingual,
   check: ({ site, issue }) => {
     const locales = site.localeAxis.locales.join(", ");
@@ -2797,62 +2801,57 @@ var hreflangMissing = {
     );
   }
 };
-var hreflangSitemapMismatch = {
-  id: "hreflang.sitemap-mismatch",
-  severity: "warning",
-  summary: "`<head>` alternates and sitemap locale coverage must agree",
-  appliesTo: (site) => isMultilingual(site) && (site.discovery?.urls.length ?? 0) > 0,
-  check: ({ site, issue }) => {
-    const bySitemap = sitemapLocalesByRoute(site);
-    const findings = [];
-    for (const page of site.pages) {
-      const head = declaredLocales(page);
-      if (head.size === 0) continue;
-      let pathname;
-      try {
-        pathname = new URL(page.fetch.finalUrl).pathname;
-      } catch {
-        continue;
-      }
-      const route = rowOf(site, page.fetch.finalUrl, pathname);
-      const inSitemap = bySitemap.get(route);
-      if (!inSitemap || inSitemap.size === 0) continue;
-      const onlyInSitemap = sorted(new Set([...inSitemap].filter((l) => !head.has(l))));
-      const onlyInHead = sorted(new Set([...head].filter((l) => !inSitemap.has(l))));
-      if (onlyInSitemap.length === 0 && onlyInHead.length === 0) continue;
-      const parts = [];
-      if (onlyInSitemap.length > 0) {
-        parts.push(
-          `the sitemap lists ${onlyInSitemap.join(", ")} but the \`<head>\` does not advertise ${onlyInSitemap.length > 1 ? "them" : "it"}`
-        );
-      }
-      if (onlyInHead.length > 0) {
-        parts.push(
-          `the \`<head>\` advertises ${onlyInHead.join(", ")} but the sitemap has no entry for ${onlyInHead.length > 1 ? "them" : "it"}`
-        );
-      }
-      findings.push(
-        issue({
-          pageUrl: page.fetch.finalUrl,
-          message: `Route \`${route}\`: ${parts.join("; ")}. Both are derived from the same intent and must not disagree.`,
-          origin: { kind: "link", rel: "alternate" },
-          fix: {
-            title: "Derive both from one locale-availability source",
-            snippet: [
-              "// Compute availability once, feed both the <head> and the sitemap.",
-              "const localesFor = (slug: string) =>",
-              "  allDocs.filter((d) => d.slug === slug && !d.draft).map((d) => d.locale);",
-              "",
-              "// generateMetadata(): alternates.languages \u2190 localesFor(slug)",
-              "// sitemap.ts:        alternates.languages \u2190 localesFor(slug)"
-            ].join("\n"),
-            language: "ts"
-          }
-        })
-      );
+function coverageGaps(site) {
+  const bySitemap = sitemapLocalesByRoute(site);
+  const gaps = [];
+  for (const page of site.pages) {
+    const head = declaredLocales(page);
+    if (head.size === 0) continue;
+    let pathname;
+    try {
+      pathname = new URL(page.fetch.finalUrl).pathname;
+    } catch {
+      continue;
     }
-    return findings;
+    const route = rowOf(site, page.fetch.finalUrl, pathname);
+    const inSitemap = bySitemap.get(route);
+    if (!inSitemap || inSitemap.size === 0) continue;
+    gaps.push({
+      page,
+      route,
+      onlyInSitemap: sorted(new Set([...inSitemap].filter((l) => !head.has(l))))
+    });
   }
+  return gaps;
+}
+var ONE_SOURCE_FIX = {
+  title: "Derive both from one locale-availability source",
+  snippet: [
+    "// Compute availability once, feed both the <head> and the sitemap.",
+    "const localesFor = (slug: string) =>",
+    "  allDocs.filter((d) => d.slug === slug && !d.draft).map((d) => d.locale);",
+    "",
+    "// generateMetadata(): alternates.languages \u2190 localesFor(slug)",
+    "// sitemap.ts:        alternates.languages \u2190 localesFor(slug)"
+  ].join("\n"),
+  language: "ts"
+};
+var bothApply = (site) => isMultilingual(site) && (site.discovery?.urls.length ?? 0) > 0;
+var hreflangClusterIncomplete = {
+  id: "hreflang.cluster-incomplete",
+  severity: "warning",
+  summary: "Every locale the sitemap publishes must appear in the route's `hreflang` cluster",
+  rigor: "vendor-spec",
+  sources: ["google-hreflang"],
+  appliesTo: bothApply,
+  check: ({ site, issue }) => coverageGaps(site).filter((gap) => gap.onlyInSitemap.length > 0).map(
+    ({ page, route, onlyInSitemap }) => issue({
+      pageUrl: page.fetch.finalUrl,
+      message: `Route \`${route}\`: the sitemap lists ${onlyInSitemap.join(", ")} but the \`<head>\` does not advertise ${onlyInSitemap.length > 1 ? "them" : "it"}. The site publishes ${onlyInSitemap.length > 1 ? "those versions" : "that version"} and leaves ${onlyInSitemap.length > 1 ? "them" : "it"} outside the cluster, so ${onlyInSitemap.length > 1 ? "they compete" : "it competes"} with this page instead of consolidating with it.`,
+      origin: { kind: "link", rel: "alternate" },
+      fix: ONE_SOURCE_FIX
+    })
+  )
 };
 function metaRobotsTokens(page) {
   const raw = page.meta.robots?.value ?? "";
@@ -3156,6 +3155,84 @@ var sitemapEntryInvalidUrl = {
     });
   }
 };
+var DOCUMENT_URL_LIMIT = 5e4;
+var DOCUMENT_BYTE_LIMIT = 52428800;
+function declaredCount(doc) {
+  return doc.kind === "index" ? doc.childLocs.length : doc.urlCount;
+}
+function oversizedDocuments(site) {
+  return (site.discovery?.documents ?? []).filter(
+    (doc) => doc.kind !== "unparsable" && (declaredCount(doc) > DOCUMENT_URL_LIMIT || doc.byteLength > DOCUMENT_BYTE_LIMIT)
+  );
+}
+var sitemapLimitsExceeded = {
+  id: "sitemap.limits.exceeded",
+  severity: "error",
+  summary: "No single sitemap document may exceed 50,000 entries or 50 MB",
+  rigor: "spec-required",
+  sources: ["sitemaps-protocol"],
+  appliesTo: (site) => oversizedDocuments(site).length > 0,
+  check: ({ site, issue }) => oversizedDocuments(site).map((doc) => {
+    const count2 = declaredCount(doc);
+    const noun = doc.kind === "index" ? "child sitemaps" : "URLs";
+    const over = [];
+    if (count2 > DOCUMENT_URL_LIMIT) {
+      over.push(`${count2.toLocaleString("en-US")} ${noun} against a ceiling of 50,000`);
+    }
+    if (doc.byteLength > DOCUMENT_BYTE_LIMIT) {
+      over.push(
+        `${(doc.byteLength / 1048576).toFixed(1)} MB uncompressed against a ceiling of 50 MB`
+      );
+    }
+    return issue({
+      pageUrl: doc.url,
+      message: `This sitemap document declares ${over.join(" and ")}. A consumer may stop reading at the limit, so everything past it is published in name only \u2014 split the document and reference the parts from an index.`,
+      origin: { kind: "computed" }
+    });
+  })
+};
+function outOfScopeEntries(site) {
+  const out = [];
+  for (const entry of site.discovery?.urls ?? []) {
+    if (!entry.documentUrl) continue;
+    let scope;
+    let loc;
+    try {
+      scope = new URL(entry.documentUrl);
+      loc = new URL(entry.loc);
+    } catch {
+      continue;
+    }
+    const prefix = scope.pathname.replace(/[^/]*$/, "");
+    if (prefix === "/") continue;
+    if (loc.origin !== scope.origin) continue;
+    if (loc.pathname.startsWith(prefix)) continue;
+    out.push({ loc: entry.loc, from: entry.documentUrl });
+  }
+  return out;
+}
+var sitemapEntryOutOfScope = {
+  id: "sitemap.entry.out-of-scope",
+  severity: "error",
+  summary: "A sitemap may only list URLs under its own directory",
+  rigor: "spec-required",
+  sources: ["sitemaps-protocol"],
+  appliesTo: (site) => outOfScopeEntries(site).length > 0,
+  check: ({ site, issue }) => {
+    const bad = outOfScopeEntries(site);
+    const byDocument = /* @__PURE__ */ new Map();
+    for (const { loc, from } of bad) {
+      byDocument.set(from, [...byDocument.get(from) ?? [], loc]);
+    }
+    return [...byDocument].map(
+      ([from, locs]) => issue({
+        pageUrl: from,
+        message: `${locs.length} entr${locs.length === 1 ? "y is" : "ies are"} outside this sitemap's directory \`${new URL(from).pathname.replace(/[^/]*$/, "")}\`: ${sample(locs)}. A sitemap only speaks for the path it is served from, so a consumer may drop ${locs.length === 1 ? "it" : "them"} \u2014 serve the document from the root, or move the entries into a sitemap that covers them.`,
+        origin: { kind: "computed" }
+      })
+    );
+  }
+};
 var sitemapEntryCrossHost = {
   id: "sitemap.entry.cross-host",
   severity: "error",
@@ -3485,7 +3562,7 @@ function isAbsolute(value) {
 }
 var SITE_RULES = [
   hreflangMissing,
-  hreflangSitemapMismatch,
+  hreflangClusterIncomplete,
   iconsIcoMissing,
   robotsBlocksPage,
   robotsBlocksSite,
@@ -3501,12 +3578,14 @@ var SITE_RULES = [
   sitemapEntryInvalidUrl,
   sitemapEntryNoindex,
   sitemapEntryNonCanonical,
+  sitemapEntryOutOfScope,
   sitemapEntryProtocolMismatch,
   sitemapEntryRedirects,
   sitemapEntryUnreachable,
   sitemapFieldInvalid,
   sitemapIndexChildError,
   sitemapLastmodInvalid,
+  sitemapLimitsExceeded,
   sitemapMissing,
   sitemapOrphans,
   sitemapUnparsable
@@ -3778,9 +3857,23 @@ async function discoverSitemap(baseUrl, options = {}) {
     diagnostics.atWellKnownPath = isWellKnownPath(candidate.url);
     const collected = [];
     const seen = /* @__PURE__ */ new Set();
+    const documents = [];
     let truncated = false;
+    documents.push({
+      url: candidate.url,
+      status: doc.status,
+      byteLength: doc.byteLength,
+      gzipped: doc.gzipped,
+      kind: parsed.kind === "index" ? "index" : "urlset",
+      childLocs: parsed.kind === "index" ? [...parsed.sitemaps] : [],
+      // What the document declares, not what survived dedupe and the cap: the
+      // ceiling is on the file's contents, and a post-dedupe count would answer
+      // a question the protocol never asked.
+      urlCount: parsed.kind === "urlset" ? parsed.urls.length : 0,
+      declaredInRobots: candidate.declaredInRobots
+    });
     if (parsed.kind === "urlset") {
-      truncated = pushEntries(collected, seen, parsed.urls, maxUrls);
+      truncated = pushEntries(collected, seen, parsed.urls, maxUrls, candidate.url);
     } else {
       diagnostics.isIndex = true;
       const children = parsed.sitemaps.slice(0, maxSitemaps);
@@ -3798,17 +3891,44 @@ async function discoverSitemap(baseUrl, options = {}) {
         }
         const childDoc = await fetchDoc(childUrl, options);
         if (!childDoc.body) {
+          documents.push({
+            url: childUrl,
+            status: childDoc.status,
+            byteLength: childDoc.byteLength,
+            gzipped: childDoc.gzipped,
+            kind: "unparsable",
+            childLocs: [],
+            urlCount: 0,
+            declaredInRobots: declaredUrls.includes(childUrl),
+            parentUrl: candidate.url
+          });
           diagnostics.childSitemapErrors += 1;
           diagnostics.warnings.push(`Child sitemap unreachable: ${childUrl}`);
           continue;
         }
         const childParsed = parseSitemap(childDoc.body);
+        documents.push({
+          url: childUrl,
+          status: childDoc.status,
+          byteLength: childDoc.byteLength,
+          gzipped: childDoc.gzipped,
+          // A child that is itself an index is recorded as one. This run still
+          // treats it as an error below, because that is what it has always
+          // done and replacing that verdict needs a source no specification
+          // provides — see `docs/sitemap-robots-plan.md` §4.3. The tree now
+          // says which of the two it was, which is the part that was lost.
+          kind: childParsed.kind === "unknown" ? "unparsable" : childParsed.kind,
+          childLocs: childParsed.kind === "index" ? [...childParsed.sitemaps] : [],
+          urlCount: childParsed.kind === "urlset" ? childParsed.urls.length : 0,
+          declaredInRobots: declaredUrls.includes(childUrl),
+          parentUrl: candidate.url
+        });
         if (childParsed.kind !== "urlset") {
           diagnostics.childSitemapErrors += 1;
           diagnostics.warnings.push(`Child sitemap not a urlset: ${childUrl}`);
           continue;
         }
-        if (pushEntries(collected, seen, childParsed.urls, maxUrls)) truncated = true;
+        if (pushEntries(collected, seen, childParsed.urls, maxUrls, childUrl)) truncated = true;
       }
     }
     diagnostics.urlCount = collected.length;
@@ -3820,6 +3940,7 @@ async function discoverSitemap(baseUrl, options = {}) {
       baseUrl,
       source: candidate.source,
       urls: collected,
+      documents,
       diagnostics,
       truncated
     };
@@ -3828,7 +3949,15 @@ async function discoverSitemap(baseUrl, options = {}) {
     return crawlSite(baseUrl, origin, options, diagnostics);
   }
   diagnostics.warnings.push("No sitemap found.");
-  return { origin, baseUrl, source: "well-known", urls: [], diagnostics, truncated: false };
+  return {
+    origin,
+    baseUrl,
+    source: "well-known",
+    urls: [],
+    documents: [],
+    diagnostics,
+    truncated: false
+  };
 }
 async function crawlSite(baseUrl, origin, options, diagnostics) {
   const result = await crawl({
@@ -3852,16 +3981,20 @@ async function crawlSite(baseUrl, origin, options, diagnostics) {
     baseUrl,
     source: "crawl",
     urls,
+    // No document declared these: the crawl found them by following links. An
+    // empty tree is the honest answer, and the rules that read it are the ones
+    // that judge documents — which this run has none of.
+    documents: [],
     diagnostics,
     truncated: result.truncated
   };
 }
-function pushEntries(out, seen, entries, cap) {
+function pushEntries(out, seen, entries, cap, documentUrl) {
   for (const entry of entries) {
     if (out.length >= cap) return true;
     if (seen.has(entry.loc)) continue;
     seen.add(entry.loc);
-    out.push(entry);
+    out.push({ ...entry, documentUrl });
   }
   return out.length >= cap;
 }
@@ -3890,26 +4023,29 @@ async function fetchDoc(url, options) {
         accept: "application/xml,text/xml,application/gzip;q=0.9,*/*;q=0.5"
       }
     });
-    if (!res.ok) return { status: res.status };
+    if (!res.ok) return { status: res.status, byteLength: 0, gzipped: false };
     const encoding = res.headers.get("content-encoding")?.toLowerCase() ?? "";
     const looksGzip = url.toLowerCase().endsWith(".gz") || encoding.includes("gzip");
     if (looksGzip) {
       const buf = Buffer.from(await res.arrayBuffer());
       try {
-        return { status: res.status, body: gunzipSync(buf).toString("utf8") };
+        return withLength(res.status, gunzipSync(buf).toString("utf8"), true);
       } catch {
-        return { status: res.status, body: buf.toString("utf8") };
+        return withLength(res.status, buf.toString("utf8"), true);
       }
     }
-    return { status: res.status, body: await res.text() };
+    return withLength(res.status, await res.text(), false);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
-    return { status: 0, error: reason || "network error" };
+    return { status: 0, error: reason || "network error", byteLength: 0, gzipped: false };
   } finally {
     cleanup();
     restoreTls();
   }
 }
+function withLength(status, body, gzipped) {
+  return { status, body, byteLength: Buffer.byteLength(body, "utf8"), gzipped };
+}
 function relaxTlsIfRequested2(enabled) {
   if (!enabled) return () => void 0;
   const previous = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
@@ -4794,6 +4930,89 @@ var PROSE_RULES = [
 ];
 var PROSE_RULE_BY_ID = new Map(PROSE_RULES.map((r) => [r.id, r]));
 
+// src/lib/rules/site-prose.ts
+var hreflangSitemapMismatch = {
+  id: "hreflang.sitemap-mismatch",
+  summary: "`<head>` alternates advertise a locale the sitemap does not list",
+  prose: "Your `<head>` advertises a translation your sitemap does not list. Is the sitemap missing an entry, or is the alternate pointing at a page you did not mean to publish?",
+  why: "The two are derived from one intent by different code paths, so a disagreement means one of them is wrong. No specification says which: the declaration methods are equivalent, and a page can legitimately be cross-linked and kept out of the sitemap.",
+  appliesTo: (site) => site.localeAxis.multilingual && (site.discovery?.urls.length ?? 0) > 0,
+  ask: (site) => {
+    const axis = new Set(site.localeAxis.locales.map((l) => l.toLowerCase()));
+    const bySitemap = /* @__PURE__ */ new Map();
+    for (const entry of site.discovery?.urls ?? []) {
+      let pathname;
+      try {
+        pathname = new URL(entry.loc).pathname;
+      } catch {
+        continue;
+      }
+      const { locale } = splitRoute(pathname);
+      if (locale === "x-default") continue;
+      if (!axis.has(locale.toLowerCase())) continue;
+      const route = site.clusterRouteOf?.(entry.loc) ?? splitRoute(pathname).route;
+      const set = bySitemap.get(route) ?? /* @__PURE__ */ new Set();
+      set.add(locale.toLowerCase());
+      bySitemap.set(route, set);
+    }
+    const drafts = [];
+    for (const page of site.pages) {
+      const head = /* @__PURE__ */ new Set();
+      for (const alt of page.links.alternates) {
+        if (alt.isXDefault) continue;
+        const tag = alt.hreflang?.trim().toLowerCase();
+        if (tag) head.add(tag);
+      }
+      if (head.size === 0) continue;
+      let pathname;
+      try {
+        pathname = new URL(page.fetch.finalUrl).pathname;
+      } catch {
+        continue;
+      }
+      const route = site.clusterRouteOf?.(page.fetch.finalUrl) ?? splitRoute(pathname).route;
+      const inSitemap = bySitemap.get(route);
+      if (!inSitemap || inSitemap.size === 0) continue;
+      const unlisted = [...head].filter((l) => !inSitemap.has(l)).sort();
+      if (unlisted.length === 0) continue;
+      drafts.push({
+        pageUrl: page.fetch.finalUrl,
+        evidence: {
+          route,
+          // Both sides, verbatim and sorted, so an agent can see the shape of
+          // the disagreement rather than take our word for its size.
+          headAdvertises: [...head].sort(),
+          sitemapLists: [...inSitemap].sort(),
+          advertisedButUnlisted: unlisted
+        }
+      });
+    }
+    return drafts;
+  }
+};
+var SITE_PROSE_RULES = [hreflangSitemapMismatch];
+function collectSiteAdvisories(site, rules = SITE_PROSE_RULES) {
+  const out = [];
+  for (const rule of rules) {
+    if (rule.appliesTo && !rule.appliesTo(site)) continue;
+    for (const draft of rule.ask(site)) {
+      out.push({
+        ruleId: rule.id,
+        kind: "prose",
+        prose: rule.prose,
+        // `null` where nothing supports the question, which is exactly the
+        // state this rule is in and the reason it stopped being a verdict.
+        rigor: rule.rigor ?? null,
+        sources: rule.sources ?? [],
+        evidence: draft.evidence,
+        verdict: "needs-judgment",
+        pageUrl: draft.pageUrl
+      });
+    }
+  }
+  return out;
+}
+
 // src/lib/core/links/extract.ts
 import * as cheerio3 from "cheerio";
 var ANCHOR_SPEC = { selector: "a[href]", attr: "href", source: "a" };
@@ -5501,6 +5720,14 @@ async function runAudit(inputUrl, options = {}) {
       sources: draft.sources
     };
   });
+  if (options.advisories) {
+    for (const advisory of collectSiteAdvisories(siteContext)) {
+      advisories.push({
+        ...advisory,
+        id: fingerprint("advisory", advisory.ruleId, routeKey(advisory.pageUrl))
+      });
+    }
+  }
   const brokenLinks = [];
   for (const { pageUrl, broken } of linkReport.brokenByPage) {
     for (const check of broken) {
@@ -5637,6 +5864,10 @@ function syntheticDiscovery(origin, baseUrl, pages, truncated) {
     baseUrl,
     source: "crawl",
     urls: pages.map((p) => ({ loc: p.fetch.finalUrl })),
+    // Crawl-derived: no sitemap document was read, so the tree is empty rather
+    // than absent. The document rules ask "what did each document declare?" and
+    // must see that nothing declared anything.
+    documents: [],
     diagnostics: {
       found: false,
       status: 0,
@@ -6277,6 +6508,7 @@ export {
   PROFILES,
   PROFILE_NAMES,
   PROSE_RULES,
+  SITE_PROSE_RULES,
   routeKey,
   targetKey,
   fingerprint,
@@ -6289,4 +6521,4 @@ export {
   summarize,
   Logger
 };
-//# sourceMappingURL=chunk-DKGBLJ4H.js.map
+//# sourceMappingURL=chunk-CWEJ6EXT.js.map