blume 1.0.4 → 1.1.1

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

@@ -7,6 +7,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type {
+  Diagnostic,
   FeaturedLink,
   NavNode,
   Navigation,
@@ -56,7 +57,17 @@ interface MutablePage {
   badge?: string;
   deprecated?: boolean;
   pageId: string;
+  /** Absolute source path (filesystem adapter only), to anchor diagnostics. */
+  file?: string;
   order: number;
+  /**
+   * Whether `order` reflects a deliberate authoring choice (explicit
+   * `sidebar.order`, a numeric filename prefix, or a folder-meta `pages` rank)
+   * rather than a derived value like a changelog entry's publish date — two
+   * changelog entries published on the same day aren't an authoring mistake,
+   * so they're excluded from the duplicate-order diagnostic.
+   */
+  orderIsAuthored: boolean;
 }
 
 interface MutableGroup {
@@ -110,24 +121,35 @@ const ensureGroup = (
   return group;
 };
 
-const pageOrder = (page: PageRecord, filename: string): number => {
+const pageOrder = (
+  page: PageRecord,
+  filename: string
+): { order: number; orderIsAuthored: boolean } => {
   if (page.meta.sidebar.order !== undefined) {
-    return page.meta.sidebar.order;
+    return { order: page.meta.sidebar.order, orderIsAuthored: true };
   }
   if (isIndexStem(filename.replace(extname(filename), ""))) {
-    return Number.NEGATIVE_INFINITY;
+    return { order: Number.NEGATIVE_INFINITY, orderIsAuthored: false };
   }
   // Changelog entries read newest-first, matching the generated timeline. Sort
   // on the negated publish timestamp so a later date yields a smaller order
   // under the ascending comparator; undated entries fall back to filename order.
+  // The date is derived, not an authoring choice, so same-day entries aren't a
+  // duplicate-order mistake.
   if (page.contentType === "changelog") {
     const iso = page.meta.date ?? page.meta.changelog?.date;
     const time = iso ? Date.parse(iso) : Number.NaN;
     if (!Number.isNaN(time)) {
-      return -time;
+      return { order: -time, orderIsAuthored: false };
     }
   }
-  return numericOrder(filename);
+  // An undated changelog entry's numeric filename prefix is usually a date
+  // (`2024-01-05-release.md`) rather than a rank, so it is derived too.
+  const order = numericOrder(filename);
+  return {
+    order,
+    orderIsAuthored: page.contentType !== "changelog" && Number.isFinite(order),
+  };
 };
 
 /**
@@ -166,6 +188,9 @@ const applyFolderMeta = (
         const position = rank.get(child.key);
         if (position !== undefined) {
           child.order = position;
+          if (child.kind === "page") {
+            child.orderIsAuthored = true;
+          }
         }
       }
     }
@@ -178,7 +203,108 @@ const applyFolderMeta = (
   }
 };
 
-const sortNodes = (nodes: MutableNode[]): void => {
+/**
+ * Warn when an index page's own frontmatter title diverges from its folder's
+ * explicit `meta.title`. The sidebar label and the page's own `<title>`/heading
+ * are resolved from two independent sources — under i18n, a translator can
+ * update the folder's `meta.ts` and forget the index page's own frontmatter
+ * (or vice versa), and a correct-looking sidebar hides the mismatch.
+ *
+ * Only fires when the page has an explicit frontmatter `title` of its own:
+ * when it's absent, `page.title` is derived from the first heading or the
+ * filename, so it almost never coincidentally matches a custom folder title —
+ * flagging that would be noise on exactly the plain-landing-page case this is
+ * least worth warning about. The root group's `meta.title` (an empty
+ * `folderPath`) is also skipped: nothing ever renders it as a sidebar label,
+ * so a mismatch there wouldn't correspond to anything visible.
+ *
+ * Fallback-filled pages are exempt: their title belongs to the fallback
+ * locale, so comparing it against this locale's `meta.title` would flag every
+ * not-yet-translated index page (once per locale) and point the suggestion at
+ * the fallback locale's source file, where "fixing" it would break that
+ * locale. The default locale's own build still checks the real page.
+ */
+const indexTitleMismatchDiagnostic = (
+  page: PageRecord,
+  folderPath: string,
+  folderMeta: Map<string, FolderMeta>,
+  sharedMeta: Map<string, FolderMeta>,
+  metaPrefix: string
+): Diagnostic | undefined => {
+  if (!page.meta.title || page.fallback || folderPath === "") {
+    return undefined;
+  }
+  const meta =
+    folderMeta.get(metaKey(folderPath, metaPrefix)) ??
+    sharedMeta.get(folderPath);
+  if (!meta?.title || meta.title === page.title) {
+    return undefined;
+  }
+  return {
+    code: "BLUME_NAV_INDEX_TITLE_MISMATCH",
+    file: page.sourcePath ?? page.id,
+    message: `Index page "${page.navPath}" has title "${page.title}", but its folder's meta.title is "${meta.title}" — the sidebar shows the folder title while the page's own <title>/heading still say "${page.title}".`,
+    severity: "warning",
+    suggestion: `Update the page's frontmatter title to match ("${meta.title}"), or leave it if the divergence is intentional.`,
+  };
+};
+
+/** Whether a node's `order` reflects a deliberate authoring choice. */
+const isAuthoredOrder = (node: MutableNode): boolean =>
+  node.kind === "group" || node.orderIsAuthored;
+
+/**
+ * Warn when two sibling nodes share an explicit/numeric order (frontmatter
+ * `sidebar.order`, a numeric filename prefix, or folder-meta `order`) — they'd
+ * otherwise fall back to a silent, arbitrary alphabetical tiebreak. Nodes at
+ * the default fallback order (no numeric prefix, no explicit order) are
+ * excluded: that's the common, intentional case of "just sort alphabetically."
+ * So is a derived, non-authored order (e.g. two changelog entries published
+ * on the same day) — not an authoring mistake.
+ */
+const duplicateOrderDiagnostics = (nodes: MutableNode[]): Diagnostic[] => {
+  const byOrder = new Map<number, MutableNode[]>();
+  for (const node of nodes) {
+    if (!Number.isFinite(node.order) || !isAuthoredOrder(node)) {
+      continue;
+    }
+    const tied = byOrder.get(node.order);
+    if (tied) {
+      tied.push(node);
+    } else {
+      byOrder.set(node.order, [node]);
+    }
+  }
+  const diagnostics: Diagnostic[] = [];
+  for (const [order, tied] of byOrder) {
+    if (tied.length > 1) {
+      const names = tied.map((node) => `"${node.label}"`);
+      const list =
+        names.length > 2
+          ? `${names.slice(0, -1).join(", ")}, and ${names.at(-1)}`
+          : names.join(" and ");
+      const verb = tied.length > 2 ? "all have" : "both have";
+      // Anchor the diagnostic to one tied source file so tooling can point
+      // somewhere concrete; the message names the rest. Folder-only ties
+      // (folder-meta `order`) have no single file, so `file` stays unset.
+      const file = tied.find(
+        (node): node is MutablePage => node.kind === "page"
+      )?.file;
+      diagnostics.push({
+        code: "BLUME_DUPLICATE_SIDEBAR_ORDER",
+        file,
+        message: `${list} ${verb} sidebar order ${order}; falling back to alphabetical order.`,
+        severity: "warning",
+        suggestion:
+          "Give each item a distinct sidebar.order (or folder meta order).",
+      });
+    }
+  }
+  return diagnostics;
+};
+
+const sortNodes = (nodes: MutableNode[], diagnostics: Diagnostic[]): void => {
+  diagnostics.push(...duplicateOrderDiagnostics(nodes));
   nodes.sort((a, b) => {
     if (a.order !== b.order) {
       return a.order - b.order;
@@ -187,7 +313,7 @@ const sortNodes = (nodes: MutableNode[]): void => {
   });
   for (const node of nodes) {
     if (node.kind === "group") {
-      sortNodes(node.children);
+      sortNodes(node.children, diagnostics);
     }
   }
 };
@@ -263,20 +389,37 @@ const buildFileSystemSidebar = (
   sharedMeta: Map<string, FolderMeta>,
   metaPrefix: string,
   display: SidebarDisplay,
-  tabPaths: Set<string>
+  tabPaths: Set<string>,
+  diagnostics: Diagnostic[] = []
 ): NavNode[] => {
   const root = createGroup("", "", "", 0);
 
   for (const page of pages) {
-    if (page.meta.sidebar.hidden) {
-      continue;
-    }
     // Group by the locale-stripped path so the locale dir is not a nav group.
     const parts = page.navPath.split("/");
     const filename = parts.at(-1) ?? page.navPath;
     const stem = filename.replace(extname(filename), "");
     const dirs = parts.slice(0, -1);
 
+    // Checked before the hidden filter: a sidebar-hidden index page still
+    // renders with its own <title>, so title drift matters there just the same.
+    if (isIndexStem(stem)) {
+      const diagnostic = indexTitleMismatchDiagnostic(
+        page,
+        dirs.join("/"),
+        folderMeta,
+        sharedMeta,
+        metaPrefix
+      );
+      if (diagnostic) {
+        diagnostics.push(diagnostic);
+      }
+    }
+
+    if (page.meta.sidebar.hidden) {
+      continue;
+    }
+
     // Each group's URL path is the matching prefix of the page's route. navPath
     // is locale-stripped while the route may carry a locale/base prefix, so
     // align the folder segments from the right (the extra leading segments are
@@ -301,22 +444,25 @@ const buildFileSystemSidebar = (
       parent.routePath ??= `/${folderParts.slice(0, consumed).join("/")}`;
     }
 
+    const { order, orderIsAuthored } = pageOrder(page, filename);
     parent.children.push({
       badge: page.meta.sidebar.badge,
       deprecated: page.meta.deprecated || undefined,
       description: page.description,
+      file: page.sourcePath,
       icon: page.meta.sidebar.icon,
       key: segmentKey(stem),
       kind: "page",
       label: page.meta.sidebar.label ?? page.title,
-      order: pageOrder(page, filename),
+      order,
+      orderIsAuthored,
       pageId: page.id,
       route: page.route,
     });
   }
 
   applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix);
-  sortNodes(root.children);
+  sortNodes(root.children, diagnostics);
   hoistPages(root.children, display === "flat");
   hoistTabSections(root.children, tabPaths, display === "flat");
   return root.children.map((child) => toNavNode(child, display));
@@ -500,6 +646,12 @@ export const buildNavigation = (
      * scoping.
      */
     localizedRoot?: string;
+    /**
+     * Sink for diagnostics produced while building the tree (duplicate sidebar
+     * `order` values, index-page title/folder-meta-title mismatches). Pushed
+     * into in place; omit to discard.
+     */
+    diagnostics?: Diagnostic[];
   }
 ): Navigation => {
   const basePath = options.basePath ?? "";
@@ -583,7 +735,10 @@ export const buildNavigation = (
     sharedFolderMeta,
     metaPrefix,
     display,
-    new Set(tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path])))
+    new Set(
+      tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
+    ),
+    options.diagnostics
   );
   return {
     featured,

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;
+};