blume 2.1.0 → 2.1.1

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;

package/src/audit/run.ts

@@ -69,6 +69,8 @@ export interface AuditOptions {
   origin?: string;
   /** Probe outbound links (`--external`). */
   external?: boolean;
+  /** Outbound URLs not to probe (`--ignore`). */
+  ignore?: (url: string) => boolean;
   /** Only report these check ids or categories. */
   only?: string[];
   /** Suppress these check ids or categories. */
@@ -159,6 +161,7 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
       siteOrigin(project.config.deployment.options.site),
       normalizeBasePath(project.config.deployment.options.base)
     ),
+    ignore: options.ignore ?? (() => false),
     llms: crawl.llms,
     origin,
     pages: crawl.pages,

package/src/audit/types.ts

@@ -249,6 +249,8 @@ export interface AuditContext {
   robots: RobotsDoc | null;
   llms: LlmsDoc | null;
   thresholds: AuditThresholds;
+  /** Outbound URLs the external tier doesn't probe (`--ignore`). */
+  ignore: (url: string) => boolean;
 }
 
 /** One category's checks. Modules, not per-check closures — see catalog.ts. */

package/src/audit/url.ts

@@ -45,10 +45,11 @@ export type ResolvedHref =
   | { 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.
+   * whole build under the base, so nothing in the build answers here — `path`
+   * is the path as requested, base missing. `absolute` when the href spelled
+   * out the origin: a full URL can name another app on the same host.
    */
-  | { kind: "outside-base"; path: string }
+  | { kind: "outside-base"; path: string; absolute: boolean }
   /** An absolute URL on another origin. */
   | { kind: "external"; url: string }
   /** In-page anchor, `mailto:`, `tel:`, `javascript:`, data URI — not a page link. */
@@ -139,7 +140,11 @@ export const resolveHref = (
     if (origin && parsed.origin === origin) {
       const served = decodePath(parsed.pathname);
       if (!underBase(deployBase, served)) {
-        return { kind: "outside-base", path: normalizePath(served) };
+        return {
+          absolute: true,
+          kind: "outside-base",
+          path: normalizePath(served),
+        };
       }
       return {
         hash: parsed.hash.slice(1),
@@ -171,7 +176,11 @@ export const resolveHref = (
   // (`./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 {
+      absolute: false,
+      kind: "outside-base",
+      path: normalizePath(served),
+    };
   }
   return {
     hash: resolved.hash.slice(1),

package/src/blume-modules.d.ts

@@ -12,7 +12,11 @@ declare module "blume:search-client" {
   // biome-ignore lint/style/useImportType: ambient module must stay a global script
   // oxlint-disable-next-line typescript/consistent-type-imports
   type Fn = import("./components/layout/search/types.ts").SearchFn;
-  export const createSearch: () => Fn | Promise<Fn>;
+  type Options =
+    // biome-ignore lint/style/useImportType: ambient module must stay a global script
+    // oxlint-disable-next-line typescript/consistent-type-imports
+    import("./components/layout/search/types.ts").SearchClientOptions;
+  export const createSearch: (options?: Options) => Fn | Promise<Fn>;
 }
 
 declare module "blume:consent-client" {

package/src/cli/args.ts

@@ -1,3 +1,5 @@
+import picomatch from "picomatch";
+
 import { logger } from "./log.ts";
 
 const MAX_PORT = 65_535;
@@ -22,6 +24,55 @@ export const parsePort = (value?: string): number | undefined => {
   return port;
 };
 
+/**
+ * Every value a repeatable string flag was given (`--ignore a --ignore b`), in
+ * order. citty 0.2 parses with `node:util.parseArgs` without its `multiple`
+ * option, so the parsed `args` keep only the last value; this reads the raw
+ * arguments the way that parser does instead: `--name=value`, or `--name`
+ * followed by the next token whatever it looks like (`""` when there is
+ * none), and nothing after a bare `--`.
+ */
+export const repeatedFlag = (
+  rawArgs: readonly string[],
+  name: string
+): string[] => {
+  const flag = `--${name}`;
+  const values: string[] = [];
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === "--") {
+      break;
+    }
+    if (arg === flag) {
+      values.push(rawArgs[index + 1] ?? "");
+      index += 1;
+    } else if (arg?.startsWith(`${flag}=`)) {
+      values.push(arg.slice(flag.length + 1));
+    }
+  }
+  return values;
+};
+
+/**
+ * The `--ignore` globs of `blume validate` and `blume audit`, as a test for
+ * the external URLs they skip: any glob matching the full URL skips it, with
+ * `dot` set so `**` also crosses a segment like `/.well-known/`. No globs skip
+ * nothing. An empty one (`--ignore` with nothing after it) exits with an
+ * error: it names no URL, and picomatch throws on it.
+ */
+export const parseIgnoreFlag = (
+  rawArgs: readonly string[]
+): ((url: string) => boolean) => {
+  const globs = repeatedFlag(rawArgs, "ignore");
+  if (globs.includes("")) {
+    logger.error(
+      'Invalid --ignore "": pass a glob for the URLs to skip (e.g. --ignore "https://example.com/**").'
+    );
+    process.exit(1);
+  }
+  return picomatch(globs, { dot: true });
+};
+
 /**
  * The longest `--timeout` a timer can hold, in seconds. Node clamps a
  * `setTimeout` delay above 2^31−1 ms (about 24.8 days) to 1 ms, so a larger

package/src/cli/build-failure.ts

@@ -20,8 +20,31 @@ const buildErrorSchema = z.looseObject({
     .optional(),
 });
 
+/**
+ * The diagnostic a `BlumeError` thrown inside the build carries, such as a
+ * failed hosted search sync in `astro:build:done`. The hook runs Blume's
+ * source rather than the CLI bundle, so its error is another copy of the class
+ * that the command's `instanceof BlumeError` doesn't recognize.
+ */
+const blumeErrorSchema = z.looseObject({
+  diagnostic: z.object({
+    code: z.string(),
+    column: z.number().optional(),
+    docsUrl: z.string().optional(),
+    file: z.string().optional(),
+    line: z.number().optional(),
+    message: z.string(),
+    severity: z.enum(["error", "info", "warning"]),
+    suggestion: z.string().optional(),
+  }),
+});
+
 /** One failure as a diagnostic at the file (and position) it names. */
 const failureDiagnostic = (error: Error): Diagnostic => {
+  const raised = blumeErrorSchema.safeParse(error);
+  if (raised.success) {
+    return raised.data.diagnostic;
+  }
   const parsed = buildErrorSchema.safeParse(error);
   const { id, loc } = parsed.success ? parsed.data : {};
   // A named error (`MDXError`, `CompilerError`) says which step failed.

package/src/cli/commands/audit.ts

@@ -15,6 +15,7 @@ import { isHttpUrl } from "../../audit/url.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { DiagnosticSeverity } from "../../core/types.ts";
+import { parseIgnoreFlag } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger, reportDiagnostics } from "../log.ts";
@@ -103,6 +104,12 @@ export const auditCommand = defineCommand({
         "Exit non-zero at this severity or above: error | warning | info. Defaults to error.",
       type: "string",
     },
+    ignore: {
+      description:
+        'With --external, skip outbound links whose URL matches this glob (e.g. "https://example.com/**"). Repeat it for more; internal links are always checked.',
+      type: "string",
+      valueHint: "glob",
+    },
     json: {
       description: "Emit the report as JSON on stdout (for CI/editors).",
       type: "boolean",
@@ -134,7 +141,7 @@ export const auditCommand = defineCommand({
     },
   },
   meta: commandMeta.audit,
-  async run({ args }) {
+  async run({ args, rawArgs }) {
     if (args["list-checks"]) {
       process.stdout.write(formatCatalog());
       return;
@@ -172,6 +179,7 @@ export const auditCommand = defineCommand({
     const only = splitTerms(args.only);
     const skip = splitTerms(args.skip);
     rejectUnknownTerms([...only, ...skip]);
+    const ignore = parseIgnoreFlag(rawArgs);
     let result: AuditResult;
     try {
       // `scanProject`, not `prepareProject`: the audit reads the *existing*
@@ -180,6 +188,7 @@ export const auditCommand = defineCommand({
       const project = await scanProject(root, { mode: "build" });
       result = await runAudit({
         external: args.external,
+        ignore,
         only,
         origin: args.url,
         project,

package/src/cli/commands/dev.ts

@@ -11,7 +11,9 @@ import {
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { resolveRuntimeDir } from "../../core/project.ts";
+import { referenceSpecFiles } from "../../openapi/references.ts";
 import { parsePort } from "../args.ts";
+import { astroBuildDiagnostics } from "../build-failure.ts";
 import { commandMeta } from "../command-meta.ts";
 import {
   acquireDevLock,
@@ -140,7 +142,19 @@ export const devCommand = defineCommand({
         server: { host: normalizeHost(args.host), open, port: listenPort },
       });
 
-    let server = await createServer(explicitPort, args.open ?? false);
+    let server: Awaited<ReturnType<typeof createServer>>;
+    try {
+      server = await createServer(explicitPort, args.open ?? false);
+    } catch (error) {
+      // Astro's first content sync rejects on a page it can't load (front
+      // matter that isn't valid YAML): report it at the file it names, as
+      // `blume build` does, not as an internal error blaming Blume.
+      if (error instanceof BlumeError || !(error instanceof Error)) {
+        throw error;
+      }
+      reportDiagnostics(astroBuildDiagnostics(error), root);
+      process.exit(1);
+    }
 
     // Vite bumps to the next free port when the default is taken, so record
     // the port the server actually bound — the lock's URL is what a refused
@@ -229,7 +243,8 @@ export const devCommand = defineCommand({
 
     // Content is watched per source (filesystem uses fs.watch; remote sources
     // are frozen for the session). The remaining project inputs — user pages,
-    // config, theme, and component overrides — are watched directly.
+    // config, theme, component overrides, and the local specs and overlays API
+    // references read — are watched directly.
     const dirTargets = [project.context.pagesRoot].filter(
       (target) => target !== null
     );
@@ -237,6 +252,7 @@ export const devCommand = defineCommand({
       project.context.configFile,
       project.context.themeFile,
       project.context.componentsFile,
+      ...referenceSpecFiles(project.config, root),
     ].filter((target) => target !== null);
 
     // chokidar handles what raw fs.watch made us hand-roll: recursive

package/src/cli/commands/doctor.ts

@@ -5,13 +5,17 @@ import { defineCommand } from "citty";
 import { join } from "pathe";
 import { satisfies } from "semver";
 
+import { discoverExamples } from "../../astro/examples.ts";
 import { discoverIslands } from "../../astro/islands.ts";
+import { discoverPages, navTargetRoutes } from "../../astro/pages.ts";
 import { missingDependencyDiagnostic } from "../../astro/runtime-deps.ts";
+import { missingExampleDiagnostics } from "../../core/component-diagnostics.ts";
 import {
   analyzeComponentOverrides,
   ComponentOverridesError,
 } from "../../core/component-overrides.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
+import { validateNavTargets } from "../../core/nav-diagnostics.ts";
 import { packageRoot } from "../../core/package-root.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
@@ -35,23 +39,24 @@ const FALLBACK_NODE_RANGE = ">=22.12.0";
  * Plan `components.ts` the way `blume dev`/`build` do, reporting each override
  * that can't be planned — a non-static form, or an import of a file that
  * doesn't exist — with its own line. The scan alone never reads the file, so
- * without this doctor would pass a project whose build fails.
+ * without this doctor would pass a project whose build fails. Also returns
+ * the MDX tags the file overrides.
  */
 const componentsDiagnostics = async (
   componentsFile: string | null
-): Promise<Diagnostic[]> => {
+): Promise<{ issues: Diagnostic[]; mdx: string[] }> => {
   if (!componentsFile) {
-    return [];
+    return { issues: [], mdx: [] };
   }
   try {
-    analyzeComponentOverrides(
+    const { mdx } = analyzeComponentOverrides(
       await readFile(componentsFile, "utf-8"),
       componentsFile
     );
-    return [];
+    return { issues: [], mdx: mdx.map((entry) => entry.key) };
   } catch (error) {
     if (error instanceof ComponentOverridesError) {
-      return error.issues;
+      return { issues: error.issues, mdx: [] };
     }
     throw error;
   }
@@ -117,15 +122,33 @@ export const doctorCommand = defineCommand({
     loadEnvFiles(root);
 
     try {
-      const project = await scanProject(root, { mode: "build" });
+      const project = await scanProject(root, {
+        // A missing secret fails at the first request. Checked before the
+        // sources fetch, so it's still reported when one of them fails the
+        // scan for want of it.
+        beforeSources: (config) => {
+          diagnostics.push(...checkRequiredSecrets(config));
+        },
+        mode: "build",
+      });
+      // Tabs, selector items, and featured links can point at custom pages
+      // and generated routes too, so they're checked against every route
+      // the site serves, as `blume dev`/`build` check them.
+      const userPages = project.context.pagesRoot
+        ? await discoverPages(project.context.pagesRoot)
+        : [];
       diagnostics.push(
         ...project.diagnostics,
-        ...unregisteredSnapshotDiagnostics(project)
+        ...unregisteredSnapshotDiagnostics(project),
+        ...validateNavTargets(
+          project.graph.navigation,
+          navTargetRoutes(project, userPages)
+        )
       );
 
       const { config } = project;
-      // The packages and secrets a build would need: an adapter's missing SDK
-      // fails the build, and a missing secret fails at the first request.
+      // The packages a build would need: an adapter's missing SDK fails the
+      // build.
       const { islands } = await discoverIslands(root);
       const dependencies = await missingDependencyDiagnostic(
         config,
@@ -136,9 +159,19 @@ export const doctorCommand = defineCommand({
       if (dependencies) {
         diagnostics.push(dependencies);
       }
+      const overrides = await componentsDiagnostics(
+        project.context.componentsFile
+      );
       diagnostics.push(
-        ...(await componentsDiagnostics(project.context.componentsFile)),
-        ...checkRequiredSecrets(config)
+        ...overrides.issues,
+        // A `<Component path>` naming no example renders a "No example
+        // found" box, which dev and build warn about too.
+        ...missingExampleDiagnostics(
+          project.graph.pages,
+          await discoverExamples(root, config.examples.source),
+          root,
+          new Set([...islands.map((island) => island.name), ...overrides.mdx])
+        )
       );
       const features = serverFeatures(config);
       if (