blume 2.0.0 → 2.0.2

package/src/audit/checks/network.ts

@@ -180,8 +180,10 @@ export const networkChecks: CheckModule = {
       found.push(...servedPageChecks(context, page, result, origin));
     }
 
+    // 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);
-    if (robots && !robots.ok) {
+    if (context.project.config.seo.robots && robots && !robots.ok) {
       found.push(
         finding(
           "BLUME_AUDIT_ROBOTS_NOT_ACCESSIBLE",

package/src/audit/checks/og-image.ts

@@ -71,6 +71,16 @@ export const ogImageChecks: CheckModule = {
       if (resolved.kind === "external" || resolved.kind === "ignored") {
         continue;
       }
+      if (resolved.kind === "outside-base") {
+        found.push(
+          finding(
+            "BLUME_AUDIT_OG_IMAGE_BROKEN",
+            pageSite(context, page, ["seo", "image"]),
+            `og:image points at ${resolved.path}, which is missing deployment.base (${deployBase}), so the deployed site does not serve it.`
+          )
+        );
+        continue;
+      }
 
       const { path } = resolved;
       if (

package/src/audit/checks/robots.ts

@@ -47,7 +47,12 @@ export const robotsChecks: CheckModule = {
       )
     );
 
-    if (site && robots.sitemaps.length === 0) {
+    // Blume only writes the Sitemap line when there is a sitemap to point at.
+    if (
+      site &&
+      context.project.config.seo.sitemap &&
+      robots.sitemaps.length === 0
+    ) {
       found.push(
         finding(
           "BLUME_AUDIT_ROBOTS_SITEMAP_MISSING",

package/src/audit/checks/sitemap.ts

@@ -138,6 +138,40 @@ const checkListedUrl = (
   return found;
 };
 
+/**
+ * The other direction: a page that was built, is indexable, and should be
+ * findable — but never made it into the sitemap. A page that names another
+ * URL as its canonical (an archived-version page pointing at the latest docs)
+ * and an i18n fallback copy are left out of the sitemap on purpose: it lists
+ * canonical URLs only (see NON_CANONICAL_IN_SITEMAP).
+ */
+const unlistedPages = (
+  context: AuditContext,
+  listed: Map<string, string>,
+  deployBase: string
+): Diagnostic[] =>
+  context.pages.flatMap((page) => {
+    const canonical = page.canonical
+      ? canonicalPath(page.canonical, deployBase)
+      : null;
+    if (
+      !page.indexable ||
+      page.route?.fallback ||
+      (canonical && canonical !== normalizePath(page.url)) ||
+      ERROR_ROUTES.has(page.url) ||
+      listed.has(normalizePath(page.url))
+    ) {
+      return [];
+    }
+    return [
+      finding(
+        "BLUME_AUDIT_INDEXABLE_PAGE_NOT_IN_SITEMAP",
+        pageSite(context, page),
+        `${page.url} is built and indexable but is not listed in sitemap.xml.`
+      ),
+    ];
+  });
+
 /**
  * The sitemap, cross-checked against what was actually built.
  *
@@ -175,23 +209,32 @@ export const sitemapChecks: CheckModule = {
         finding(
           "BLUME_AUDIT_SITEMAP_INVALID",
           { file: sitemap.file, url: "/sitemap.xml" },
-          `sitemap.xml is not a valid urlset: ${sitemap.error}`
+          `sitemap.xml is not a valid urlset or sitemap index: ${sitemap.error}`
         )
       );
       return found;
     }
 
-    if (
-      sitemap.bytes > MAX_SITEMAP_BYTES ||
-      sitemap.urls.length > MAX_SITEMAP_URLS
-    ) {
-      found.push(
-        finding(
-          "BLUME_AUDIT_SITEMAP_TOO_LARGE",
-          { file: sitemap.file, url: "/sitemap.xml" },
-          `sitemap.xml holds ${sitemap.urls.length} URLs in ${Math.round(sitemap.bytes / 1024 / 1024)} MB.`
-        )
-      );
+    // The limits are per file: a sitemap index splits a large site across
+    // urlsets, each of which must fit on its own.
+    const parts = sitemap.parts ?? [
+      {
+        bytes: sitemap.bytes,
+        file: sitemap.file,
+        url: "/sitemap.xml",
+        urls: sitemap.urls.length,
+      },
+    ];
+    for (const part of parts) {
+      if (part.bytes > MAX_SITEMAP_BYTES || part.urls > MAX_SITEMAP_URLS) {
+        found.push(
+          finding(
+            "BLUME_AUDIT_SITEMAP_TOO_LARGE",
+            { file: part.file, url: part.url },
+            `${part.url.slice(1)} holds ${part.urls} URLs in ${Math.round(part.bytes / 1024 / 1024)} MB.`
+          )
+        );
+      }
     }
 
     // A `<lastmod>` that lies — malformed, or claiming the future — teaches
@@ -230,25 +273,7 @@ export const sitemapChecks: CheckModule = {
       );
     }
 
-    // The other direction: a page that was built, is indexable, and should be
-    // findable — but never made it into the sitemap.
-    for (const page of context.pages) {
-      if (
-        !page.indexable ||
-        ERROR_ROUTES.has(page.url) ||
-        listed.has(normalizePath(page.url))
-      ) {
-        continue;
-      }
-      found.push(
-        finding(
-          "BLUME_AUDIT_INDEXABLE_PAGE_NOT_IN_SITEMAP",
-          pageSite(context, page),
-          `${page.url} is built and indexable but is not listed in sitemap.xml.`
-        )
-      );
-    }
-
+    found.push(...unlistedPages(context, listed, deployBase));
     return found;
   },
   tier: "static",

package/src/audit/checks/social.ts

@@ -1,7 +1,8 @@
+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 type { CheckModule, PageSnapshot } from "../types.ts";
+import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 import { normalizePath } from "../url.ts";
 
 /** The Open Graph properties a share card is unusable without. */
@@ -175,6 +176,23 @@ const URL_STYLE: { name: string; test: RegExp }[] = [
   { name: "spaces", test: /%20| /u },
 ];
 
+/**
+ * The part of a page URL its author named: the URL minus a leading i18n locale
+ * segment. A locale code like `pt-BR` is BCP 47 casing set once in config,
+ * not an untidy slug, so it must not trip the uppercase check on every page
+ * of that locale. The segment follows `basePath`, which page URLs carry.
+ */
+const authoredPath = (context: AuditContext, url: string): string => {
+  const { basePath, i18n } = context.project.config;
+  if (!i18n) {
+    return url;
+  }
+  const base = normalizeBasePath(basePath);
+  const [, first = "", ...rest] = stripBasePath(base, url).split("/");
+  const isLocale = i18n.locales.some((locale) => locale.code === first);
+  return isLocale ? `${base}/${rest.join("/")}` : url;
+};
+
 /** A protocol-relative URL names a dotted host (`//cdn.example.com/x`). */
 const DOTTED_HOST = /^\/\/[^/]*\./u;
 
@@ -220,7 +238,8 @@ export const urlChecks: CheckModule = {
         }
       }
 
-      const untidy = URL_STYLE.filter((style) => style.test.test(page.url));
+      const authored = authoredPath(context, page.url);
+      const untidy = URL_STYLE.filter((style) => style.test.test(authored));
       if (untidy.length > 0) {
         found.push(
           finding(

package/src/audit/crawl.ts

@@ -125,6 +125,11 @@ type XmlValue =
 const isUrlsetElement = (value: XmlValue): value is { url?: XmlValue } =>
   typeof value === "object" && value !== null;
 
+const isSitemapIndexElement = (
+  value: XmlValue
+): value is { sitemap?: XmlValue } =>
+  typeof value === "object" && value !== null;
+
 const isUrlEntry = (
   value: XmlValue
 ): value is { lastmod?: XmlValue; loc?: XmlValue } =>
@@ -134,7 +139,9 @@ const isText = (value: XmlValue): value is string => typeof value === "string";
 
 /**
  * Parse `sitemap.xml`. Deliberately shallow: the checks only need the `<loc>`
- * list, each loc's `<lastmod>`, and whether the document is a urlset at all.
+ * list, each loc's `<lastmod>`, and whether the document is a urlset at all —
+ * or, for a sitemap index, the child sitemaps it lists (`sitemaps`), which
+ * the crawler reads from the build.
  */
 export const parseSitemap = (
   file: string,
@@ -149,10 +156,20 @@ export const parseSitemap = (
     doc.error = "no <urlset> element";
     return doc;
   }
+  if (Object.hasOwn(parsed, "sitemapindex")) {
+    const { sitemapindex } = parsed;
+    const children = isSitemapIndexElement(sitemapindex)
+      ? [sitemapindex.sitemap].flat()
+      : [];
+    doc.sitemaps = children.flatMap((child) =>
+      isUrlEntry(child) && isText(child.loc) && child.loc.trim()
+        ? [child.loc.trim()]
+        : []
+    );
+    return doc;
+  }
   if (!Object.hasOwn(parsed, "urlset")) {
-    doc.error = Object.hasOwn(parsed, "sitemapindex")
-      ? "sitemap is an index, not a urlset"
-      : "no <urlset> element";
+    doc.error = "no <urlset> element";
     return doc;
   }
   const { urlset } = parsed;
@@ -252,6 +269,69 @@ const readIfPresent = async (file: string): Promise<string | null> => {
   }
 };
 
+/**
+ * Read `sitemap.xml`, following it through a sitemap index: each child
+ * sitemap is read from the build (its `<loc>` carries the site origin and the
+ * deployment base, the file tree neither) and its URLs merged into the one
+ * document the checks see. A child that can't be resolved, is missing, or
+ * isn't a urlset makes the whole document invalid.
+ */
+const readSitemap = async (
+  staticDir: string,
+  files: Map<string, number>,
+  deployBase: string
+): Promise<SitemapDoc | null> => {
+  const file = join(staticDir, "sitemap.xml");
+  const xml = await readIfPresent(file);
+  if (xml === null) {
+    return null;
+  }
+  const doc = parseSitemap(
+    file,
+    xml,
+    files.get("/sitemap.xml") ?? Buffer.byteLength(xml, "utf-8")
+  );
+  if (!doc.sitemaps) {
+    return doc;
+  }
+  doc.parts = [];
+  for (const loc of doc.sitemaps) {
+    let url: string;
+    try {
+      url = stripBasePath(deployBase, decodeURI(new URL(loc).pathname));
+    } catch {
+      doc.error = `the sitemap index lists "${loc}", which is not a valid absolute URL`;
+      return doc;
+    }
+    const childFile = join(staticDir, url);
+    // oxlint-disable-next-line no-await-in-loop -- one read per child, in index order
+    const childXml = await readIfPresent(childFile);
+    const child =
+      childXml === null
+        ? null
+        : parseSitemap(
+            childFile,
+            childXml,
+            files.get(url) ?? Buffer.byteLength(childXml, "utf-8")
+          );
+    if (!child || child.error || child.sitemaps) {
+      doc.error = `the sitemap index lists ${loc}, which is not a urlset in the build`;
+      return doc;
+    }
+    doc.urls.push(...child.urls);
+    for (const [key, value] of child.lastmod ?? []) {
+      doc.lastmod?.set(key, value);
+    }
+    doc.parts.push({
+      bytes: child.bytes,
+      file: childFile,
+      url,
+      urls: child.urls.length,
+    });
+  }
+  return doc;
+};
+
 /**
  * Read the built site: every HTML page reduced to a snapshot, the full file
  * index (for resolving subresource references), plus sitemap.xml and robots.txt.
@@ -260,8 +340,10 @@ export const crawlStaticDir = async (options: {
   staticDir: string;
   manifest: BlumeManifest;
   basePath: string;
+  /** The normalized `deployment.base`, which sitemap-index `<loc>`s carry. */
+  deployBase?: string;
 }): Promise<CrawlResult> => {
-  const { staticDir, manifest, basePath } = options;
+  const { staticDir, manifest, basePath, deployBase = "" } = options;
   const routes = routeIndex(manifest, basePath);
 
   const htmlFiles = await glob("**/*.html", { absolute: true, cwd: staticDir });
@@ -287,8 +369,6 @@ export const crawlStaticDir = async (options: {
   );
   const pages = snapshots.filter((page) => page !== null);
 
-  const sitemapFile = join(staticDir, "sitemap.xml");
-  const sitemapXml = await readIfPresent(sitemapFile);
   const robotsFile = join(staticDir, "robots.txt");
   const robotsTxt = await readIfPresent(robotsFile);
   const llmsFile = join(staticDir, "llms.txt");
@@ -300,13 +380,6 @@ export const crawlStaticDir = async (options: {
     llms: llmsText === null ? null : parseLlms(llmsFile, llmsText),
     pages,
     robots: robotsTxt === null ? null : parseRobots(robotsFile, robotsTxt),
-    sitemap:
-      sitemapXml === null
-        ? null
-        : parseSitemap(
-            sitemapFile,
-            sitemapXml,
-            files.get("/sitemap.xml") ?? Buffer.byteLength(sitemapXml, "utf-8")
-          ),
+    sitemap: await readSitemap(staticDir, files, deployBase),
   };
 };

package/src/audit/report.ts

@@ -33,12 +33,47 @@ const TIER_FLAGS: { tier: AuditTier; flag: string }[] = [
 interface CheckRollup {
   id: CheckId;
   count: number;
+  /** Distinct affected URLs — one page can carry several findings. */
+  pages: number;
   severity: DiagnosticSeverity;
   category: AuditCategory;
   title: string;
   findings: Diagnostic[];
 }
 
+const SEVERITY_ORDER = {
+  error: 0,
+  info: 2,
+  warning: 1,
+} satisfies Record<DiagnosticSeverity, number>;
+
+/**
+ * The group's severity: the worst of its findings'. A check can downgrade a
+ * finding at runtime (an external link answering 503 is a warning, not the
+ * catalog's error), and the group's glyph must agree with the summary counts.
+ */
+const worstSeverity = (findings: Diagnostic[]): DiagnosticSeverity => {
+  let worst: DiagnosticSeverity = "info";
+  for (const finding of findings) {
+    if (SEVERITY_ORDER[finding.severity] < SEVERITY_ORDER[worst]) {
+      worst = finding.severity;
+    }
+  }
+  return worst;
+};
+
+/** The first finding per affected URL, in report order. */
+const firstPerPage = (findings: Diagnostic[]): Diagnostic[] => {
+  const seen = new Set<string | undefined>();
+  return findings.filter((finding) => {
+    if (seen.has(finding.url)) {
+      return false;
+    }
+    seen.add(finding.url);
+    return true;
+  });
+};
+
 /**
  * Group findings by check. This is the difference between a report people read
  * and one they close: 214 pages × 6 findings is an unreadable wall, but "Meta
@@ -55,22 +90,18 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
     }
   }
 
-  const order = {
-    error: 0,
-    info: 2,
-    warning: 1,
-  } satisfies Record<DiagnosticSeverity, number>;
   const checks = [...groups.entries()].map(([id, findings]) => {
     // SAFETY: audit findings are only ever created through `finding()`, whose
     // codes are the check catalog's ids.
     const checkId = id as CheckId;
-    const { category, severity, title } = checkMeta(checkId);
+    const { category, title } = checkMeta(checkId);
     return {
       category,
       count: findings.length,
       findings,
       id: checkId,
-      severity,
+      pages: firstPerPage(findings).length,
+      severity: worstSeverity(findings),
       title,
     };
   });
@@ -80,7 +111,7 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
   // and print "content" three separate times.
   const worst = new Map<AuditCategory, number>();
   for (const check of checks) {
-    const rank = order[check.severity];
+    const rank = SEVERITY_ORDER[check.severity];
     worst.set(
       check.category,
       Math.min(worst.get(check.category) ?? rank, rank)
@@ -91,7 +122,7 @@ export const rollup = (diagnostics: Diagnostic[]): CheckRollup[] => {
     (a, b) =>
       (worst.get(a.category) ?? 0) - (worst.get(b.category) ?? 0) ||
       a.category.localeCompare(b.category) ||
-      order[a.severity] - order[b.severity] ||
+      SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
       b.count - a.count
   );
 };
@@ -176,14 +207,16 @@ export const formatReport = (
     }
 
     const color = SEVERITY_COLOR[group.severity];
-    const pages = `${group.count} page${group.count === 1 ? "" : "s"}`;
+    const pages = `${group.pages} page${group.pages === 1 ? "" : "s"}`;
     lines.push(
       `  ${color(`${GLYPH[group.severity]} ${group.title}`)}  ${colors.dim(pages)}`
     );
 
+    // The preview lists affected pages, each once; --verbose lists every
+    // finding, since each one's message names a different specific.
     const shown = options.verbose
       ? group.findings
-      : group.findings.slice(0, PREVIEW);
+      : firstPerPage(group.findings).slice(0, PREVIEW);
     for (const diagnostic of shown) {
       lines.push(findingLine(diagnostic, root));
       // The message names the specifics the rolled-up line can't — which target
@@ -192,16 +225,20 @@ export const formatReport = (
         lines.push(`        ${colors.dim(diagnostic.message)}`);
       }
     }
-    const hidden = group.count - shown.length;
+    const hidden = options.verbose ? 0 : group.pages - shown.length;
     if (hidden > 0) {
       lines.push(`      ${colors.dim(`… and ${hidden} more (--verbose)`)}`);
     }
 
-    // Every finding in a group shares the catalog's fix unless it overrode it,
-    // so showing the first one's is showing the group's.
-    const [first] = group.findings;
-    const fix = first?.suggestion;
-    if (fix) {
+    // Findings share the catalog's fix unless one overrode it (a navigation
+    // entry, a page generated from an API spec), so each distinct fix is
+    // printed once.
+    const fixes = new Set(
+      group.findings.flatMap((finding) =>
+        finding.suggestion ? [finding.suggestion] : []
+      )
+    );
+    for (const fix of fixes) {
       lines.push(`      ${colors.cyan(`fix: ${fix}`)}`);
     }
     lines.push("");

package/src/audit/run.ts

@@ -137,6 +137,7 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
 
   const crawl = await crawlStaticDir({
     basePath,
+    deployBase: normalizeBasePath(project.config.deployment.options.base),
     manifest: project.manifest,
     staticDir,
   });

package/src/audit/types.ts

@@ -113,6 +113,16 @@ export interface RedirectResolution {
   outcome: "ok" | "loop" | "broken" | "chain";
 }
 
+/** One urlset file behind a sitemap, for the per-file size limits. */
+export interface SitemapPart {
+  file: string;
+  /** Site path the file is served at, e.g. `/sitemap-1.xml`. */
+  url: string;
+  bytes: number;
+  /** How many `<url>` entries the file lists. */
+  urls: number;
+}
+
 /** A parsed `sitemap.xml`. */
 export interface SitemapDoc {
   file: string;
@@ -121,6 +131,14 @@ export interface SitemapDoc {
   urls: string[];
   /** Each `<url>` block's `<lastmod>`, keyed by its `<loc>`. */
   lastmod?: Map<string, string>;
+  /**
+   * The child sitemaps' `<loc>`s, when `sitemap.xml` is a sitemap index —
+   * Blume writes one past 50,000 URLs. The crawler reads each child from the
+   * build and merges its URLs into `urls` and `lastmod`.
+   */
+  sitemaps?: string[];
+  /** The index's child urlset files, once the crawler has read them. */
+  parts?: SitemapPart[];
   /** Parse failure, when the document isn't usable. */
   error?: string;
 }

package/src/audit/url.ts

@@ -43,11 +43,21 @@ export type ResolvedHref =
   | { kind: "internal"; path: string; hash: string }
   /** An absolute URL that resolves back to this site — should have been a path. */
   | { kind: "self-origin"; path: string; hash: string }
+  /**
+   * A path on this origin that lacks `deployment.base`. The host serves the
+   * whole build under the base, so nothing answers here — `path` is the path
+   * as requested, base missing.
+   */
+  | { kind: "outside-base"; path: string }
   /** An absolute URL on another origin. */
   | { kind: "external"; url: string }
   /** In-page anchor, `mailto:`, `tel:`, `javascript:`, data URI — not a page link. */
   | { kind: "ignored" };
 
+/** Whether a served path sits under the deployment base (always, without one). */
+const underBase = (deployBase: string, path: string): boolean =>
+  !deployBase || path === deployBase || path.startsWith(`${deployBase}/`);
+
 const NON_HTTP_SCHEME = /^(?!https?:)[a-z][a-z0-9+.-]*:/iu;
 
 /**
@@ -65,6 +75,20 @@ export const decodePath = (path: string): string => {
   }
 };
 
+/**
+ * Whether a `--url` value is an absolute http(s) URL the network tier can
+ * probe. A bare host (`example.com`) has no scheme, and `localhost:4321`
+ * parses with `localhost:` as its scheme — both are rejected.
+ */
+export const isHttpUrl = (input: string): boolean => {
+  try {
+    const { protocol } = new URL(input);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+
 /** The origin of `deployment.site`, or null when no site is configured. */
 export const siteOrigin = (site?: string): string | null => {
   if (!site) {
@@ -113,12 +137,14 @@ export const resolveHref = (
       return { kind: "ignored" };
     }
     if (origin && parsed.origin === origin) {
+      const served = decodePath(parsed.pathname);
+      if (!underBase(deployBase, served)) {
+        return { kind: "outside-base", path: normalizePath(served) };
+      }
       return {
         hash: parsed.hash.slice(1),
         kind: "self-origin",
-        path: normalizePath(
-          stripBasePath(deployBase, decodePath(parsed.pathname))
-        ),
+        path: normalizePath(stripBasePath(deployBase, served)),
       };
     }
     return { kind: "external", url: parsed.toString() };
@@ -140,11 +166,16 @@ export const resolveHref = (
   } catch {
     return { kind: "ignored" };
   }
+  const served = decodePath(resolved.pathname);
+  // Only a root-relative href names the served path outright; a relative one
+  // (`./auth`) was resolved against the base-less page URL above, so it
+  // inherits the page's base by construction.
+  if (target.startsWith("/") && !underBase(deployBase, served)) {
+    return { kind: "outside-base", path: normalizePath(served) };
+  }
   return {
     hash: resolved.hash.slice(1),
     kind: "internal",
-    path: normalizePath(
-      stripBasePath(deployBase, decodePath(resolved.pathname))
-    ),
+    path: normalizePath(stripBasePath(deployBase, served)),
   };
 };

package/src/blume-modules.d.ts

@@ -18,9 +18,9 @@ declare module "blume:search-client" {
 declare module "blume:ask" {
   /** The generated Ask trigger (see `askComponentTemplate`); empty when Ask is off. */
   // Mirrors the generated `.blume/src/env.d.ts` declaration: the trigger's type
-  // is the AskAI island the enabled template re-exports.
+  // is the Assistant island the enabled template re-exports.
   // oxlint-disable-next-line typescript/consistent-type-imports
-  const Ask: typeof import("./components/islands/AskAI.astro").default;
+  const Ask: typeof import("./components/islands/Assistant.astro").default;
   export default Ask;
 }
 

package/src/cli/build-failure.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+import type { Diagnostic } from "../core/types.ts";
+
+/**
+ * The fields of an `astro build` rejection the report reads. Rolldown bundles
+ * every plugin failure (an MDX compile error, say) into one error whose
+ * `errors` holds each; a failure carries `loc` where the compiler pinned it,
+ * or only `id`, the module that failed.
+ */
+const buildErrorSchema = z.looseObject({
+  errors: z.array(z.instanceof(Error)).optional(),
+  id: z.string().optional(),
+  loc: z
+    .looseObject({
+      column: z.number().optional(),
+      file: z.string().optional(),
+      line: z.number().optional(),
+    })
+    .optional(),
+});
+
+/** One failure as a diagnostic at the file (and position) it names. */
+const failureDiagnostic = (error: Error): Diagnostic => {
+  const parsed = buildErrorSchema.safeParse(error);
+  const { id, loc } = parsed.success ? parsed.data : {};
+  // A named error (`MDXError`, `CompilerError`) says which step failed.
+  const name = error.name === "Error" ? "" : `${error.name}: `;
+  return {
+    code: "BLUME_BUILD_FAILED",
+    column: loc?.column,
+    file: loc?.file ?? id,
+    line: loc?.line,
+    message: `${name}${error.message}`,
+    severity: "error",
+  };
+};
+
+/**
+ * What `astro build` rejected with, as build diagnostics: one per failure
+ * Rolldown collected, else the error itself. A page Blume's own checks pass
+ * can still fail Astro's compile (MDX that doesn't parse) or render, and that
+ * is a problem in the site, reported at its file, rather than an internal
+ * error blaming Blume.
+ */
+export const astroBuildDiagnostics = (error: Error): Diagnostic[] => {
+  const parsed = buildErrorSchema.safeParse(error);
+  const failures = parsed.success ? (parsed.data.errors ?? []) : [];
+  return (failures.length > 0 ? failures : [error]).map(failureDiagnostic);
+};