blume 2.0.3 → 2.1.1

package/src/astro/variables.ts

@@ -0,0 +1,31 @@
+import { substituteVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
+
+/**
+ * The MDX half of content variables (see `core/variables.ts`): a Vite plugin
+ * that replaces `{{name}}` in an `.mdx` module's source before the MDX
+ * compiler reads it. It has to run first: the compiler parses `{{version}}`
+ * as a JavaScript expression (a `ReferenceError` at render) and rejects
+ * `{{api-url}}` outright, so no plugin after parsing could see either.
+ */
+/** The Vite plugin slice this needs (structurally typed, like Blume's other plugins). */
+export interface VariablesVitePlugin {
+  enforce: "pre";
+  name: string;
+  transform: (code: string, id: string) => { code: string; map: null } | null;
+}
+
+export const variablesVitePlugin = (
+  variables: ContentVariables
+): VariablesVitePlugin => ({
+  enforce: "pre",
+  name: "blume:variables",
+  transform(code, id) {
+    const [path = ""] = id.split("?");
+    if (!path.endsWith(".mdx")) {
+      return null;
+    }
+    const next = substituteVariables(code, variables);
+    return next === code ? null : { code: next, map: null };
+  },
+});

package/src/audit/catalog.ts

@@ -161,7 +161,7 @@ export const CHECKS = [
   },
   {
     category: "duplicates",
-    fix: "Merge the pages, or set `seo.canonical` on all but one.",
+    fix: "Merge the pages, or point `seo.canonical` on all but one at the page to index.",
     id: "BLUME_AUDIT_DUPLICATE_CONTENT",
     severity: "warning",
     tier: "static",
@@ -359,7 +359,7 @@ export const CHECKS = [
   },
   {
     category: "redirects",
-    fix: "Remove the redirect, or delete the page it shadows — the page wins and the redirect never fires.",
+    fix: "Remove the redirect, or delete the page it shadows — a path can't be both, and which one readers get depends on the host.",
     id: "BLUME_AUDIT_REDIRECT_SOURCE_IS_PAGE",
     severity: "error",
     tier: "static",
@@ -373,6 +373,14 @@ export const CHECKS = [
     tier: "network",
     title: "HTTPS to HTTP redirect",
   },
+  {
+    category: "redirects",
+    fix: "Deploy the redirect file your host reads (see Redirects in the deployment docs), or name the host in `deployment`.",
+    id: "BLUME_AUDIT_REDIRECT_NOT_SERVED",
+    severity: "error",
+    tier: "network",
+    title: "Live site doesn't redirect as configured",
+  },
 
   // Social
   {
@@ -498,6 +506,25 @@ export const CHECKS = [
     title: "Hreflang group has a language conflict",
   },
 
+  // Accessibility. Theme colors are one per site, not per page: these run
+  // on the config, the way the build resolves it.
+  {
+    category: "accessibility",
+    fix: "Pick a darker shade for light mode or a lighter one for dark mode, per mode with `theme.accent: { light, dark }`.",
+    id: "BLUME_AUDIT_THEME_CONTRAST_LOW",
+    severity: "warning",
+    tier: "static",
+    title: "Theme colors miss WCAG AA contrast",
+  },
+  {
+    category: "accessibility",
+    fix: "Write the color as hex, `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, or a named color so its contrast can be checked.",
+    id: "BLUME_AUDIT_THEME_COLOR_UNCHECKED",
+    severity: "info",
+    tier: "static",
+    title: "Theme color can't be checked for contrast",
+  },
+
   // Assets
   {
     category: "assets",
@@ -551,7 +578,7 @@ export const CHECKS = [
   // Sitemap
   {
     category: "sitemap",
-    fix: "Remove `draft`/`hidden`/`noindex` from the page's frontmatter if it should be indexed.",
+    fix: "Remove `draft`/`hidden`/`noindex` from the page's frontmatter if it should be indexed. A `public/sitemap.xml` replaces the generated sitemap, so add the page there or delete that file.",
     id: "BLUME_AUDIT_INDEXABLE_PAGE_NOT_IN_SITEMAP",
     severity: "warning",
     tier: "static",
@@ -647,6 +674,14 @@ export const CHECKS = [
     tier: "static",
     title: "robots.txt disallows a page that is in the sitemap",
   },
+  {
+    category: "robots",
+    fix: "Narrow or remove the rule in that crawler's `User-agent` group if it should read these pages. Blocking an AI crawler on purpose is fine; skip this check.",
+    id: "BLUME_AUDIT_ROBOTS_BLOCKS_CRAWLER",
+    severity: "warning",
+    tier: "static",
+    title: "robots.txt blocks one crawler from pages in the sitemap",
+  },
   {
     category: "robots",
     fix: "Set `deployment.site` so robots.txt can reference the sitemap.",

package/src/audit/checks/contrast.ts

@@ -0,0 +1,183 @@
+import type { ResolvedConfig } from "../../core/schema.ts";
+import type { Diagnostic } from "../../core/types.ts";
+import { composite, contrastRatio, parseColor } from "../../theme/color.ts";
+import type { Rgba } from "../../theme/color.ts";
+import {
+  MIN_TEXT_CONTRAST,
+  labelOn,
+  resolveAccent,
+  resolveAction,
+  themeInk,
+} from "../../theme/palette.ts";
+import type { ColorMode } from "../../theme/palette.ts";
+import { finding } from "../catalog.ts";
+import type { CheckModule } from "../types.ts";
+
+const MODES = ["light", "dark"] as const satisfies readonly ColorMode[];
+
+/** The theme config key a color comes from. */
+type ThemeKey = "theme.accent" | "theme.action" | "theme.background";
+
+/** A color the theme draws text in, over the surface it sits on. */
+interface TextPair {
+  fix: string;
+  key: ThemeKey;
+  /** What the pair is, for the message: "Accent text on the page". */
+  label: string;
+  surface: Rgba;
+  text: Rgba;
+}
+
+/** A theme color, resolved for one mode, and the config key it came from. */
+interface ThemeColor {
+  key: ThemeKey;
+  value: string;
+}
+
+/** What one mode's check found: pairs to measure, colors it couldn't read. */
+interface ModeColors {
+  pairs: TextPair[];
+  unread: ThemeColor[];
+}
+
+/** A fill and the label the build puts on it (`labelOn`, as `readableOn`). */
+const fillPair = (
+  key: "theme.accent" | "theme.action",
+  fill: Rgba,
+  page: Rgba,
+  mode: ColorMode
+): TextPair => ({
+  fix: `Neither white nor dark text reaches ${MIN_TEXT_CONTRAST}:1 on this shade. Move \`${key}\`'s ${mode} shade lighter or darker.`,
+  key,
+  label:
+    key === "theme.action"
+      ? "The call-to-action label"
+      : "Button labels on the accent",
+  surface: composite(fill, page),
+  text: parseColor(labelOn(fill, mode)) ?? fill,
+});
+
+/** The accent's pairs: accent text on the page, and labels on accent fills. */
+const accentPairs = (fill: Rgba, page: Rgba, mode: ColorMode): TextPair[] => [
+  {
+    fix: `${mode === "light" ? "Darken" : "Lighten"} \`theme.accent\`'s ${mode} shade (\`theme.accent: { light, dark }\`).`,
+    key: "theme.accent",
+    label: "Accent text on the page",
+    surface: page,
+    text: fill,
+  },
+  fillPair("theme.accent", fill, page, mode),
+];
+
+/** The pairs a custom page background sets: body and secondary text on it. */
+const backgroundPairs = (page: Rgba, mode: ColorMode): TextPair[] => {
+  const fix = `Pick a \`theme.background\` ${mode} color further from the text color.`;
+  return [
+    {
+      fix,
+      key: "theme.background",
+      label: "Body text on the page",
+      surface: page,
+      text: themeInk(mode, "foreground"),
+    },
+    {
+      fix,
+      key: "theme.background",
+      label: "Secondary text on the page",
+      surface: page,
+      text: themeInk(mode, "mutedForeground"),
+    },
+  ];
+};
+
+/** Everything one mode draws text in, from the theme config. */
+const modeColors = (
+  theme: ResolvedConfig["theme"],
+  mode: ColorMode
+): ModeColors => {
+  const unread: ThemeColor[] = [];
+  const read = (color: ThemeColor): Rgba | null => {
+    const parsed = parseColor(color.value);
+    if (!parsed) {
+      unread.push(color);
+    }
+    return parsed;
+  };
+  const custom = theme.background?.[mode];
+  const customPage =
+    custom === undefined
+      ? null
+      : read({ key: "theme.background", value: custom });
+  // Text on a page color the audit can't read can't be measured.
+  if (custom !== undefined && !customPage) {
+    return { pairs: [], unread };
+  }
+  const page = customPage ?? themeInk(mode, "background");
+  const pairs = customPage ? backgroundPairs(customPage, mode) : [];
+  const accent = read({
+    key: "theme.accent",
+    value: resolveAccent(theme)[mode],
+  });
+  if (accent) {
+    pairs.push(...accentPairs(accent, page, mode));
+  }
+  const action = resolveAction(theme);
+  const actionFill =
+    action && read({ key: "theme.action", value: action[mode] });
+  if (actionFill) {
+    pairs.push(fillPair("theme.action", actionFill, page, mode));
+  }
+  return { pairs, unread };
+};
+
+/**
+ * Theme contrast: the text colors a configured theme draws — accent text,
+ * labels on accent and call-to-action fills, and body text on a custom
+ * background — measured against WCAG AA's 4.5:1 in both color modes, resolved
+ * the way the build resolves them (presets per mode, labels by `labelOn`).
+ * One finding per failing pair, pointed at blume.config.ts, since a theme
+ * color is a site-wide choice, not a page's.
+ */
+export const contrastChecks: CheckModule = {
+  category: "accessibility",
+  run(context) {
+    const { theme } = context.project.config;
+    const site = {
+      file: context.project.context.configFile ?? undefined,
+      url: "/",
+    };
+    const found: Diagnostic[] = [];
+    const reported = new Set<string>();
+    for (const mode of MODES) {
+      const { pairs, unread } = modeColors(theme, mode);
+      for (const color of unread) {
+        const id = `${color.key}:${color.value}`;
+        if (!reported.has(id)) {
+          reported.add(id);
+          found.push(
+            finding(
+              "BLUME_AUDIT_THEME_COLOR_UNCHECKED",
+              site,
+              `\`${color.key}\` is "${color.value}", which the audit can't read as a color, so its contrast went unchecked.`
+            )
+          );
+        }
+      }
+      for (const pair of pairs) {
+        const ratio = contrastRatio(pair.text, pair.surface);
+        if (ratio < MIN_TEXT_CONTRAST) {
+          found.push(
+            finding(
+              "BLUME_AUDIT_THEME_CONTRAST_LOW",
+              site,
+              `${pair.label} in ${mode} mode is ${ratio.toFixed(2)}:1, under the ${MIN_TEXT_CONTRAST}:1 WCAG AA asks of body text (\`${pair.key}\`).`,
+              pair.fix
+            )
+          );
+        }
+      }
+    }
+    return found;
+  },
+  tier: "static",
+};

package/src/audit/checks/i18n.ts

@@ -2,6 +2,7 @@ import { normalizeBasePath, stripBasePath } from "../../core/base-path.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
+import { redirectAt } from "../redirects.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 import { decodePath, normalizePath } from "../url.ts";
 import { isArchivedLatestCanonical } from "./indexability.ts";
@@ -134,9 +135,7 @@ const hreflangChecks = (
     }
 
     const target = context.byUrl.get(path);
-    const redirect = context.redirects.find(
-      (entry) => normalizePath(entry.from) === path
-    );
+    const redirect = redirectAt(context.redirects, path);
     if (redirect) {
       found.push(
         finding(

package/src/audit/checks/indexability.ts

@@ -3,6 +3,7 @@ import type { Diagnostic } from "../../core/types.ts";
 import { deployPlatform } from "../../deploy/platforms/index.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
+import { redirectAt } from "../redirects.ts";
 import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 import { decodePath, normalizePath, siteOrigin } from "../url.ts";
@@ -118,9 +119,7 @@ const canonicalChecks = (
 
   // The canonical points at another page on this site. It must exist, and it
   // must not itself redirect — a canonical to a redirect is a dead end.
-  const redirect = context.redirects.find(
-    (entry) => normalizePath(entry.from) === target
-  );
+  const redirect = redirectAt(context.redirects, target);
   if (redirect) {
     found.push(
       finding(

package/src/audit/checks/links.ts

@@ -3,13 +3,9 @@ import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { orphanPages } from "../graph.ts";
 import { pageSite } from "../locate.ts";
-import type {
-  AuditContext,
-  CheckModule,
-  PageSnapshot,
-  SnapshotLink,
-} from "../types.ts";
-import { isServed, normalizePath, resolveHref, siteOrigin } from "../url.ts";
+import { redirectAt } from "../redirects.ts";
+import type { CheckModule, PageSnapshot, SnapshotLink } from "../types.ts";
+import { isServed, resolveHref, siteOrigin } from "../url.ts";
 
 /** Browser-magic fragments that scroll without needing a matching id. */
 const MAGIC_FRAGMENTS = new Set(["", "top"]);
@@ -33,9 +29,6 @@ const anchorResolves = (target: PageSnapshot, fragment: string): boolean => {
   }
 };
 
-const redirectFrom = (context: AuditContext, path: string) =>
-  context.redirects.find((entry) => normalizePath(entry.from) === path);
-
 /**
  * Internal links, and what they land on.
  *
@@ -108,6 +101,12 @@ export const linkChecks: CheckModule = {
         return;
       }
       if (resolved.kind === "outside-base") {
+        // A full URL on this host outside the base names another app there
+        // (the navigation docs say to link one that way), not a page of this
+        // build that lost its base.
+        if (resolved.absolute) {
+          return;
+        }
         if (link.content) {
           found.push(
             finding(
@@ -150,7 +149,7 @@ export const linkChecks: CheckModule = {
       }
 
       const { path } = resolved;
-      const redirect = redirectFrom(context, path);
+      const redirect = redirectAt(context.redirects, path);
       if (redirect) {
         if (link.content) {
           found.push(
@@ -200,7 +199,7 @@ export const linkChecks: CheckModule = {
       );
     }
     for (const [path, page] of redirectedChrome) {
-      const redirect = redirectFrom(context, path);
+      const redirect = redirectAt(context.redirects, path);
       found.push(
         finding(
           "BLUME_AUDIT_LINK_TO_REDIRECT",
@@ -222,11 +221,18 @@ export const linkChecks: CheckModule = {
 
     const homeUrl = normalizeBasePath(context.project.config.basePath) || "/";
     for (const page of orphanPages(context.pages, context.graph, homeUrl)) {
+      // A `sidebar.hidden` page is in no other page's navigation either, so
+      // it isn't reachable from the sidebar at all.
+      const fromNavigation = [
+        ...(context.graph.chromeIn.get(page.url) ?? []),
+      ].some((from) => from !== page.url);
       found.push(
         finding(
           "BLUME_AUDIT_ORPHAN_PAGE",
           pageSite(context, page),
-          "No other page's body links here — it is reachable only from the sidebar."
+          fromNavigation
+            ? "No other page's body links here — it is reachable only from the sidebar."
+            : "No page links here, from its body or from navigation, so readers and crawlers can't reach it."
         )
       );
     }

package/src/audit/checks/network.ts

@@ -1,11 +1,16 @@
-import { normalizeBasePath } from "../../core/base-path.ts";
+import { normalizeBasePath, stripBasePath } from "../../core/base-path.ts";
 import { gradeExternal, probeAll } from "../../core/probe.ts";
 import type { ProbeResult } from "../../core/probe.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
-import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
-import { resolveHref, siteOrigin } from "../url.ts";
+import type {
+  AuditContext,
+  CheckModule,
+  PageSnapshot,
+  RedirectResolution,
+} from "../types.ts";
+import { decodePath, normalizePath, resolveHref, siteOrigin } from "../url.ts";
 
 const CLIENT_ERROR = 400;
 const SERVER_ERROR = 500;
@@ -135,6 +140,79 @@ export const servedPageChecks = (
   return found;
 };
 
+/**
+ * The configured redirects the live site should answer: only those the static
+ * checks passed. A pattern (`/beta/:slug*`) names no single URL to request, a
+ * loop never lands, and a redirect whose source is also a page never fires.
+ */
+const liveRedirects = (context: AuditContext): RedirectResolution[] =>
+  context.redirects.filter(
+    (redirect) =>
+      (redirect.outcome === "ok" || redirect.outcome === "chain") &&
+      !context.byUrl.has(normalizePath(redirect.from))
+  );
+
+/**
+ * What requesting a redirect's old URL on the live site got wrong, or null
+ * when it redirected to the configured destination.
+ *
+ * The build writes the host's redirect file, but a host that doesn't read it
+ * answers with the meta-refresh page Astro writes at the old URL (a 200:
+ * readers still get there, so it's a warning), and a missing redirect 404s (an
+ * error). An external destination isn't compared: its site may redirect again.
+ */
+export const liveRedirectCheck = (
+  context: AuditContext,
+  redirect: RedirectResolution,
+  result: ProbeResult,
+  deployBase: string
+): Diagnostic | null => {
+  const from = normalizePath(redirect.from);
+  const site = {
+    file: context.project.context.configFile ?? undefined,
+    url: from,
+  };
+  const landed =
+    result.redirected && result.finalUrl
+      ? normalizePath(
+          stripBasePath(
+            deployBase,
+            decodePath(new URL(result.finalUrl).pathname)
+          )
+        )
+      : from;
+
+  // A host that only adds a trailing slash (`/old` → `/old/`) still didn't
+  // redirect to the destination.
+  if (landed === from) {
+    let answer = `could not be reached (${result.error ?? "no response"})`;
+    if (result.timedOut) {
+      answer = "did not respond in time";
+    } else if (result.status !== undefined) {
+      answer = `answered it with HTTP ${result.status} instead`;
+    }
+    const found = finding(
+      "BLUME_AUDIT_REDIRECT_NOT_SERVED",
+      site,
+      `${from} should redirect to ${redirect.to}, but the live site ${answer}.`
+    );
+    return result.ok ? { ...found, severity: "warning" } : found;
+  }
+
+  const destination = redirect.chain.at(-1) ?? from;
+  if (/^https?:\/\//iu.test(destination) || landed === destination) {
+    return null;
+  }
+  return {
+    ...finding(
+      "BLUME_AUDIT_REDIRECT_NOT_SERVED",
+      site,
+      `${from} redirects to ${landed} on the live site, not to ${destination}.`
+    ),
+    severity: "warning",
+  };
+};
+
 /**
  * The built site, checked against a live deployment.
  *
@@ -164,8 +242,23 @@ export const networkChecks: CheckModule = {
     // build output, which the host serves under the deployment base.
     const robotsUrl = new URL(`${deployBase}/robots.txt`, origin).toString();
     const sitemapUrl = new URL(`${deployBase}/sitemap.xml`, origin).toString();
+    // Each configured redirect is requested at its old URL, the way a reader
+    // following an old link arrives. Its `from` carries `basePath`; the host
+    // serves it under the deployment base too.
+    const redirects = liveRedirects(context).map(
+      (redirect) =>
+        [
+          redirect,
+          new URL(`${deployBase}${redirect.from}`, origin).toString(),
+        ] as const
+    );
 
-    const results = await probeAll([...targets, robotsUrl, sitemapUrl]);
+    const results = await probeAll([
+      ...targets,
+      robotsUrl,
+      sitemapUrl,
+      ...redirects.map(([, url]) => url),
+    ]);
 
     for (const page of context.pages) {
       const result = results.get(liveUrl(origin, page, deployBase));
@@ -180,6 +273,16 @@ export const networkChecks: CheckModule = {
       found.push(...servedPageChecks(context, page, result, origin));
     }
 
+    for (const [redirect, url] of redirects) {
+      // SAFETY: every redirect URL was in the probed list, and `probeAll`
+      // returns a result for each URL it was given.
+      const result = results.get(url) as ProbeResult;
+      const wrong = liveRedirectCheck(context, redirect, result, deployBase);
+      if (wrong) {
+        found.push(wrong);
+      }
+    }
+
     // With `seo.robots: false` Blume writes no robots.txt, so its absence on
     // the live site is the configured outcome, not a defect.
     const robots = results.get(robotsUrl);
@@ -210,7 +313,8 @@ export const networkChecks: CheckModule = {
 };
 
 /**
- * Outbound links, probed over the network (`--external`).
+ * Outbound links, probed over the network (`--external`), except those an
+ * `--ignore` glob matches.
  *
  * Severity is graded rather than flat: a 404 is the author's bug, but a 403 or a
  * 5xx is usually rate limiting or someone else's outage, and failing a build on
@@ -229,7 +333,7 @@ export const externalChecks: CheckModule = {
     for (const page of context.pages) {
       for (const link of page.links) {
         const resolved = resolveHref(page.url, link.href, origin, deployBase);
-        if (resolved.kind !== "external") {
+        if (resolved.kind !== "external" || context.ignore(resolved.url)) {
           continue;
         }
         const pages = linkers.get(resolved.url);

package/src/audit/checks/redirects.ts

@@ -23,15 +23,17 @@ export const redirectChecks: CheckModule = {
     for (const redirect of context.redirects) {
       const from = normalizePath(redirect.from);
 
-      // A redirect whose source is also a built page never fires — the page
-      // wins. Ahrefs can't see this: it only observes the served response, which
-      // looks perfectly healthy.
+      // A redirect whose source is also a built page: one of the two never
+      // serves, and which depends on the host (a static layer that answers
+      // files first keeps the page; a router that runs redirects first keeps
+      // the redirect). Ahrefs can't see this: it only observes the served
+      // response, which looks perfectly healthy.
       if (context.byUrl.has(from)) {
         found.push(
           finding(
             "BLUME_AUDIT_REDIRECT_SOURCE_IS_PAGE",
             { ...site, url: from },
-            `A redirect is configured from ${from}, but ${from} is also a real page — the redirect never fires.`
+            `A redirect is configured from ${from}, but ${from} is also a real page — readers get one or the other, depending on the host.`
           )
         );
         continue;

package/src/audit/checks/robots.ts

@@ -12,9 +12,30 @@ import { normalizePath } from "../url.ts";
  */
 const MATCH_ORIGIN = "https://robots-audit.invalid";
 
+const USER_AGENT_LINE = /^\s*user-agent\s*:\s*(?<agent>[^#]*)/iu;
+
+/**
+ * The crawlers robots.txt names in a `User-agent` line, other than `*`, as
+ * written (first spelling wins). robots-parser matches a group by the token
+ * before any `/version`, case-insensitively, so that's what dedupes them.
+ */
+const namedAgents = (raw: string): string[] => {
+  const agents = new Map<string, string>();
+  for (const line of raw.split(/\r?\n/u)) {
+    const agent = USER_AGENT_LINE.exec(line)?.groups?.agent?.trim() ?? "";
+    const key = agent.toLowerCase().split("/")[0]?.trim() ?? "";
+    if (key && key !== "*" && !agents.has(key)) {
+      agents.set(key, agent);
+    }
+  }
+  return [...agents.values()];
+};
+
 /**
  * robots.txt: is it there, is it well-formed, does it point at the sitemap, and
  * — the one that matters — does it block a page the sitemap is advertising?
+ * Blocking every crawler (`User-agent: *`) is an error; a group aimed at one
+ * crawler is a warning, since shutting out an AI crawler is often on purpose.
  *
  * Ahrefs also tracks "robots.txt has too many redirects". A static host serves
  * the file directly, so that is effectively unreachable here and isn't checked.
@@ -70,6 +91,14 @@ export const robotsChecks: CheckModule = {
     // consecutive User-agent lines form one group as the spec requires.
     const parser = robotsParser(`${MATCH_ORIGIN}/robots.txt`, robots.raw);
     const lines = robots.raw.split(/\r?\n/u);
+    const ruleAt = (url: string, agent: string) => {
+      const line = parser.getMatchingLineNumber(url, agent);
+      return { line, rule: line > 0 ? lines[line - 1]?.trim() : undefined };
+    };
+    // A crawler named in its own group follows only that group, so a rule
+    // there can block it from a page every other crawler may read.
+    const agents = namedAgents(robots.raw);
+    const blockedFor = new Map<string, string[]>();
     for (const loc of context.sitemap?.urls ?? []) {
       let pathname: string;
       try {
@@ -82,8 +111,7 @@ export const robotsChecks: CheckModule = {
       const path = normalizePath(pathname);
       const url = `${MATCH_ORIGIN}${pathname}`;
       if (parser.isDisallowed(url, "*")) {
-        const line = parser.getMatchingLineNumber(url, "*");
-        const rule = line > 0 ? lines[line - 1]?.trim() : undefined;
+        const { rule } = ruleAt(url, "*");
         found.push(
           finding(
             "BLUME_AUDIT_ROBOTS_DISALLOWS_INDEXABLE",
@@ -91,7 +119,35 @@ export const robotsChecks: CheckModule = {
             `robots.txt "${rule ?? "Disallow"}" blocks ${path}, which sitemap.xml advertises.`
           )
         );
+        continue;
       }
+      for (const agent of agents) {
+        if (!parser.isDisallowed(url, agent)) {
+          continue;
+        }
+        const blocked = blockedFor.get(agent);
+        if (blocked) {
+          blocked.push(url);
+        } else {
+          blockedFor.set(agent, [url]);
+        }
+      }
+    }
+
+    // One finding per crawler, at the rule that blocks its first page: a
+    // `Disallow: /` aimed at one bot would otherwise list every page.
+    for (const [agent, urls] of blockedFor) {
+      const [first = ""] = urls;
+      const { line, rule } = ruleAt(first, agent);
+      const path = normalizePath(new URL(first).pathname);
+      const more = urls.length > 1 ? ` and ${urls.length - 1} more` : "";
+      found.push(
+        finding(
+          "BLUME_AUDIT_ROBOTS_BLOCKS_CRAWLER",
+          { file: robots.file, line, url: "/robots.txt" },
+          `robots.txt "${rule ?? "Disallow"}" blocks ${agent} from ${path}${more}, which sitemap.xml advertises.`
+        )
+      );
     }
 
     return found;