blume 1.0.3 → 1.1.0

package/src/core/diagnostics.ts

@@ -126,17 +126,43 @@ const locatePath = (
   return { column: found - lastNewline, line: before.split("\n").length };
 };
 
-/** Convert a ZodError into Blume diagnostics, anchored to a file. */
-export const diagnosticsFromZod = (
-  error: ZodError,
+/** The YAML front matter block of a `.md`/`.mdx` source, if it has one. */
+const FRONTMATTER = /^---\r?\n(?<body>[\s\S]*?)\r?\n---/u;
+
+/**
+ * Locate a front matter key in a content file, e.g. `["seo", "description"]` in
+ * `docs/api.mdx`. Scoped to the front matter block so a `title:` written in the
+ * page body can't be mistaken for the front matter key of the same name; returns
+ * undefined when the file has no front matter or the key isn't set (a missing
+ * key has no line to point at — callers anchor to the file instead).
+ */
+export const locateFrontmatterKey = (
+  source: string,
+  path: readonly (string | number)[]
+): { column: number; line: number } | undefined => {
+  const block = FRONTMATTER.exec(source);
+  if (!block) {
+    return;
+  }
+  // `locatePath` reports lines 1-based within the text it was given, and the
+  // front matter body starts one line below the opening `---`.
+  const position = locatePath(block.groups?.body ?? "", path);
+  return position && { column: position.column, line: position.line + 1 };
+};
+
+/**
+ * Convert generic validation issues (message + path, the shape shared by Zod
+ * and Standard Schema issues) into Blume diagnostics, anchored to a file.
+ */
+export const diagnosticsFromIssues = (
+  issues: readonly {
+    message: string;
+    path: readonly (string | number)[];
+  }[],
   options: { code: string; file?: string; source?: string }
 ): Diagnostic[] =>
-  error.issues.map((issue) => {
+  issues.map((issue) => {
     const schemaPath = issue.path.join(".");
-    const received =
-      "received" in issue
-        ? ` (received: ${JSON.stringify(issue.received)})`
-        : "";
     const position = options.source
       ? locatePath(options.source, issue.path)
       : undefined;
@@ -145,14 +171,28 @@ export const diagnosticsFromZod = (
       column: position?.column,
       file: options.file,
       line: position?.line,
-      message: schemaPath
-        ? `${schemaPath}: ${issue.message}${received}`
-        : `${issue.message}${received}`,
+      message: schemaPath ? `${schemaPath}: ${issue.message}` : issue.message,
       schemaPath: schemaPath || undefined,
       severity: "error",
     } satisfies Diagnostic;
   });
 
+/** Convert a ZodError into Blume diagnostics, anchored to a file. */
+export const diagnosticsFromZod = (
+  error: ZodError,
+  options: { code: string; file?: string; source?: string }
+): Diagnostic[] =>
+  diagnosticsFromIssues(
+    error.issues.map((issue) => ({
+      message:
+        "received" in issue
+          ? `${issue.message} (received: ${JSON.stringify(issue.received)})`
+          : issue.message,
+      path: issue.path,
+    })),
+    options
+  );
+
 const ESC = String.fromCodePoint(27);
 const COLORS = {
   blue: `${ESC}[34m`,
@@ -184,13 +224,20 @@ export const formatDiagnostic = (
     `${color}${COLORS.bold}${diagnostic.code}${COLORS.reset} ${diagnostic.message}`,
   ];
 
+  // An audit finding is about a built URL, and names the source file that fixes
+  // it as a second line ("at /docs/api" / "in docs/api.mdx:3:2"). Everything
+  // else is about a file alone, and keeps the original single `at file` line.
+  if (diagnostic.url) {
+    lines.push(`  ${COLORS.dim}at ${diagnostic.url}${COLORS.reset}`);
+  }
   if (diagnostic.file) {
     const location = root ? relative(root, diagnostic.file) : diagnostic.file;
     const column =
       diagnostic.column === undefined ? "" : `:${diagnostic.column}`;
     const position =
       diagnostic.line === undefined ? "" : `:${diagnostic.line}${column}`;
-    lines.push(`  ${COLORS.dim}at ${location}${position}${COLORS.reset}`);
+    const label = diagnostic.url ? "in" : "at";
+    lines.push(`  ${COLORS.dim}${label} ${location}${position}${COLORS.reset}`);
   }
 
   if (diagnostic.suggestion) {

package/src/core/links.ts

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { basename, join } from "pathe";
 
 import { stripBasePath, withBasePath } from "./base-path.ts";
+import { gradeExternal, probeAll } from "./probe.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -25,13 +26,6 @@ const decodePercent = (value: string): string => {
 const DOC_EXT = /\.(?:md|mdx)$/iu;
 const FILE_EXT = /\.[a-z0-9]+$/iu;
 
-const EXTERNAL_CONCURRENCY = 8;
-const EXTERNAL_TIMEOUT_MS = 10_000;
-const STATUS_NOT_FOUND = 404;
-const STATUS_GONE = 410;
-const STATUS_METHOD_NOT_ALLOWED = 405;
-const STATUS_NOT_IMPLEMENTED = 501;
-
 /** Source position shared by every diagnostic raised for a link. */
 interface LinkSite {
   column: number;
@@ -214,94 +208,11 @@ const checkPathLink = (
   };
 };
 
-/** Probe a URL with the given method, normalizing failures to a result. */
-const request = async (
-  url: string,
-  method: "GET" | "HEAD"
-): Promise<{
-  ok: boolean;
-  status?: number;
-  timedOut?: boolean;
-  error?: string;
-}> => {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), EXTERNAL_TIMEOUT_MS);
-  try {
-    const response = await fetch(url, {
-      method,
-      redirect: "follow",
-      signal: controller.signal,
-    });
-    return { ok: response.ok, status: response.status };
-  } catch (error) {
-    if (error instanceof Error && error.name === "AbortError") {
-      return { ok: false, timedOut: true };
-    }
-    return {
-      error: error instanceof Error ? error.message : String(error),
-      ok: false,
-    };
-  } finally {
-    clearTimeout(timer);
-  }
-};
-
-/** Probe a single URL: HEAD first, falling back to GET when needed. */
-const probe = async (
-  url: string
-): Promise<Awaited<ReturnType<typeof request>>> => {
-  const head = await request(url, "HEAD");
-  const unreachable = !head.ok && head.status === undefined && !head.timedOut;
-  const retry =
-    head.status === STATUS_METHOD_NOT_ALLOWED ||
-    head.status === STATUS_NOT_IMPLEMENTED ||
-    unreachable;
-  return retry ? await request(url, "GET") : head;
-};
-
-/** Grade a probe result into a diagnostic severity + detail, or null if OK. */
-const gradeExternal = (
-  result: Awaited<ReturnType<typeof request>>
-): { severity: Diagnostic["severity"]; detail: string } | null => {
-  if (result.ok) {
-    return null;
-  }
-  if (result.timedOut) {
-    return { detail: "request timed out", severity: "warning" };
-  }
-  if (result.status === undefined) {
-    return { detail: result.error ?? "unreachable", severity: "error" };
-  }
-  if (result.status === STATUS_NOT_FOUND || result.status === STATUS_GONE) {
-    return { detail: `HTTP ${result.status}`, severity: "error" };
-  }
-  return { detail: `HTTP ${result.status}`, severity: "warning" };
-};
-
 /** Probe queued external links with bounded concurrency. */
 const checkExternalLinks = async (
   refs: ExternalRef[]
 ): Promise<Diagnostic[]> => {
-  const unique = [...new Set(refs.map((ref) => ref.url))];
-  const results = new Map<string, Awaited<ReturnType<typeof probe>>>();
-
-  let cursor = 0;
-  const worker = async (): Promise<void> => {
-    while (cursor < unique.length) {
-      const url = unique[cursor];
-      cursor += 1;
-      if (url !== undefined) {
-        // oxlint-disable-next-line no-await-in-loop -- bounded-concurrency pool
-        results.set(url, await probe(url));
-      }
-    }
-  };
-  await Promise.all(
-    Array.from(
-      { length: Math.min(EXTERNAL_CONCURRENCY, unique.length) },
-      worker
-    )
-  );
+  const results = await probeAll(refs.map((ref) => ref.url));
 
   const diagnostics: Diagnostic[] = [];
   for (const ref of refs) {

package/src/core/nav-diagnostics.ts

@@ -55,10 +55,13 @@ const collectIcons = (
 };
 
 /** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
-export const validateNavIcons = (navigation: Navigation): Diagnostic[] => {
+const unknownIconDiagnostics = (
+  icons: { icon: string; where: string }[],
+  suggestion: string
+): Diagnostic[] => {
   const seen = new Set<string>();
   const diagnostics: Diagnostic[] = [];
-  for (const { icon, where } of collectIcons(navigation)) {
+  for (const { icon, where } of icons) {
     if (isAssetIcon(icon) || hasIcon(icon) || seen.has(icon)) {
       continue;
     }
@@ -67,13 +70,54 @@ export const validateNavIcons = (navigation: Navigation): Diagnostic[] => {
       code: "BLUME_UNKNOWN_ICON",
       message: `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`,
       severity: "warning",
-      suggestion:
-        "Use a built-in icon name, an image path/URL, or inline SVG markup.",
+      suggestion,
     });
   }
   return diagnostics;
 };
 
+/** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
+export const validateNavIcons = (navigation: Navigation): Diagnostic[] =>
+  unknownIconDiagnostics(
+    collectIcons(navigation),
+    "Use a built-in icon name, an image path/URL, or inline SVG markup."
+  );
+
+/**
+ * Warn about unknown icons on curated `search.popular` links. Separate from
+ * {@link validateNavIcons} because these live under `search`, not the built
+ * navigation — and unlike nav icons they resolve in a *client* island, so only
+ * set names work (an image/SVG icon quietly falls back to the file glyph).
+ */
+export const validateSearchPopularIcons = (
+  popular: { icon?: string; label: string }[]
+): Diagnostic[] => {
+  const icons = popular.flatMap((link) =>
+    link.icon
+      ? [{ icon: link.icon, where: `popular link "${link.label}"` }]
+      : []
+  );
+  // Asset icons are valid in the nav, so the shared helper skips them — but
+  // here they are exactly the silent failure this validator exists to catch.
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const { icon, where } of icons) {
+    if (isAssetIcon(icon) && !seen.has(icon)) {
+      seen.add(icon);
+      diagnostics.push({
+        code: "BLUME_UNKNOWN_ICON",
+        message: `Icon "${icon}" (${where}) is an image or inline SVG — popular links render in the client search island, where only built-in icon names resolve, so it falls back to the file glyph.`,
+        severity: "warning",
+        suggestion: "Use a built-in icon name.",
+      });
+    }
+  }
+  return [
+    ...diagnostics,
+    ...unknownIconDiagnostics(icons, "Use a built-in icon name."),
+  ];
+};
+
 /** Whether an internal path resolves to a page or a section that has pages. */
 const resolvesToPages = (routes: Set<string>, path: string): boolean =>
   routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));

package/src/core/navigation.ts

@@ -433,6 +433,43 @@ const buildConfigSidebar = (
   return nodes;
 };
 
+/**
+ * Resolve a tab's clickable target. A tab's `path` scopes its sidebar section
+ * but need not be a real route — a section with no index page would 404 if the
+ * tab linked straight to it. Prefer an exact page/group at the path; otherwise
+ * fall back to the first linkable route in the section (sidebar order).
+ */
+const resolveTabHref = (sidebar: NavNode[], path: string): string => {
+  let first: string | undefined;
+  const walk = (nodes: NavNode[]): boolean => {
+    for (const node of nodes) {
+      const { route } = node;
+      if (route === path) {
+        return true;
+      }
+      if (
+        first === undefined &&
+        route !== undefined &&
+        route.startsWith(`${path}/`)
+      ) {
+        first = route;
+      }
+      if (node.kind === "group" && walk(node.children)) {
+        return true;
+      }
+    }
+    return false;
+  };
+  return walk(sidebar) ? path : (first ?? path);
+};
+
+/** Attach a resolved `href` to each tab whose section has no index page. */
+const withTabHrefs = (tabs: NavTab[], sidebar: NavNode[]): NavTab[] =>
+  tabs.map((tab) => {
+    const href = resolveTabHref(sidebar, tab.path);
+    return href === tab.path ? tab : { ...tab, href };
+  });
+
 /** Build the complete navigation model from pages, meta, and config. */
 export const buildNavigation = (
   pages: PageRecord[],
@@ -519,11 +556,17 @@ export const buildNavigation = (
   }
 
   if (options.sidebar) {
+    const sidebar = buildConfigSidebar(
+      options.sidebar,
+      byRoute,
+      display,
+      basePath
+    );
     return {
       featured,
       selectors,
-      sidebar: buildConfigSidebar(options.sidebar, byRoute, display, basePath),
-      tabs,
+      sidebar,
+      tabs: withTabHrefs(tabs, sidebar),
     };
   }
 
@@ -534,19 +577,18 @@ export const buildNavigation = (
   // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
   // under a base, falsely scope a group named like the prefix).
   const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
+  const sidebar = buildFileSystemSidebar(
+    pages,
+    options.folderMeta,
+    sharedFolderMeta,
+    metaPrefix,
+    display,
+    new Set(tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path])))
+  );
   return {
     featured,
     selectors,
-    sidebar: buildFileSystemSidebar(
-      pages,
-      options.folderMeta,
-      sharedFolderMeta,
-      metaPrefix,
-      display,
-      new Set(
-        tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
-      )
-    ),
-    tabs,
+    sidebar,
+    tabs: withTabHrefs(tabs, sidebar),
   };
 };

package/src/core/probe.ts

@@ -0,0 +1,136 @@
+import type { DiagnosticSeverity } from "./types.ts";
+
+export const PROBE_CONCURRENCY = 8;
+export const PROBE_TIMEOUT_MS = 10_000;
+
+const STATUS_NOT_FOUND = 404;
+const STATUS_GONE = 410;
+const STATUS_METHOD_NOT_ALLOWED = 405;
+const STATUS_NOT_IMPLEMENTED = 501;
+
+/** The outcome of a single HTTP probe, with failures normalized rather than thrown. */
+export interface ProbeResult {
+  ok: boolean;
+  status?: number;
+  timedOut?: boolean;
+  error?: string;
+  /** Whether the request was redirected before landing on `status`. */
+  redirected?: boolean;
+  /** The URL finally landed on, after following redirects. */
+  finalUrl?: string;
+  /** `Content-Encoding` of the response, when the server set one. */
+  encoding?: string | null;
+  /** Wall-clock milliseconds for the request. */
+  ms?: number;
+  /** `X-Robots-Tag` of the response, when the server set one. */
+  robotsTag?: string | null;
+}
+
+/** Probe a URL with the given method, normalizing failures to a result. */
+const request = async (
+  url: string,
+  method: "GET" | "HEAD",
+  timeoutMs: number
+): Promise<ProbeResult> => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const started = performance.now();
+  try {
+    const response = await fetch(url, {
+      method,
+      redirect: "follow",
+      signal: controller.signal,
+    });
+    return {
+      encoding: response.headers.get("content-encoding"),
+      finalUrl: response.url,
+      ms: Math.round(performance.now() - started),
+      ok: response.ok,
+      redirected: response.redirected,
+      robotsTag: response.headers.get("x-robots-tag"),
+      status: response.status,
+    };
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return { ok: false, timedOut: true };
+    }
+    return {
+      error: error instanceof Error ? error.message : String(error),
+      ok: false,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * Probe a single URL: HEAD first, falling back to GET.
+ *
+ * Plenty of servers reject HEAD outright (405/501) or drop the connection, so a
+ * HEAD-only probe would report healthy pages as dead.
+ */
+export const probe = async (
+  url: string,
+  options: { timeoutMs?: number } = {}
+): Promise<ProbeResult> => {
+  const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+  const head = await request(url, "HEAD", timeoutMs);
+  const unreachable = !head.ok && head.status === undefined && !head.timedOut;
+  const retry =
+    head.status === STATUS_METHOD_NOT_ALLOWED ||
+    head.status === STATUS_NOT_IMPLEMENTED ||
+    unreachable;
+  return retry ? await request(url, "GET", timeoutMs) : head;
+};
+
+/** Grade a probe result into a severity + detail, or null when the URL is fine. */
+export const gradeExternal = (
+  result: ProbeResult
+): { severity: DiagnosticSeverity; detail: string } | null => {
+  if (result.ok) {
+    return null;
+  }
+  if (result.timedOut) {
+    return { detail: "request timed out", severity: "warning" };
+  }
+  if (result.status === undefined) {
+    return { detail: result.error ?? "unreachable", severity: "error" };
+  }
+  // A 404/410 is definitively dead. A 403/429/5xx may well be rate limiting or a
+  // transient blip, which is not the author's bug to fix.
+  if (result.status === STATUS_NOT_FOUND || result.status === STATUS_GONE) {
+    return { detail: `HTTP ${result.status}`, severity: "error" };
+  }
+  return { detail: `HTTP ${result.status}`, severity: "warning" };
+};
+
+/**
+ * Probe many URLs with bounded concurrency, deduplicating first. Returns a map
+ * from URL to its result — the caller decides what each one means.
+ */
+export const probeAll = async (
+  urls: readonly string[],
+  options: { concurrency?: number; timeoutMs?: number } = {}
+): Promise<Map<string, ProbeResult>> => {
+  const unique = [...new Set(urls)];
+  const results = new Map<string, ProbeResult>();
+  const limit = Math.min(
+    options.concurrency ?? PROBE_CONCURRENCY,
+    unique.length
+  );
+
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    while (cursor < unique.length) {
+      const url = unique[cursor];
+      cursor += 1;
+      if (url !== undefined) {
+        // oxlint-disable-next-line no-await-in-loop -- bounded-concurrency pool
+        results.set(url, await probe(url, options));
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: limit }, worker));
+
+  return results;
+};

package/src/core/project-graph.ts

@@ -190,6 +190,13 @@ export const scanProject = async (
     discoverFolderMeta(metaSources, { localeDirs }),
   ]);
 
+  // Only thread `frontmatter.extend` through when a project opts in, so the
+  // known-key split in `normalizeEntry` stays off the default path.
+  const frontmatterExtend =
+    Object.keys(config.frontmatter.extend).length > 0
+      ? config.frontmatter.extend
+      : undefined;
+
   const allPages: PageRecord[] = [];
   const contentDiagnostics: Diagnostic[] = [];
   for (const { source, entries, diagnostics } of loaded) {
@@ -198,6 +205,7 @@ export const scanProject = async (
       const normalized = normalizeEntry(entry, {
         basePath: config.basePath,
         defaultType: config.content.defaultType,
+        frontmatterExtend,
         i18n: config.i18n,
         source: {
           name: source.name,