blume 1.4.2 → 1.5.0

package/src/core/navigation.ts

@@ -47,6 +47,19 @@ const segmentKey = (raw: string): string => {
 const isIndexStem = (stem: string): boolean =>
   stem.replace(NUMERIC_PREFIX, "") === "index";
 
+/** A filename's stem: the name with its extension stripped. */
+const stemOf = (filename: string): string =>
+  filename.replace(extname(filename), "");
+
+/**
+ * The stem of a nav path's last segment. The single index-detection input for
+ * the warn path (`sidebarDisplayIgnoredDiagnostics`) and the apply path
+ * (`buildFileSystemSidebar`), so the two can't drift apart on what counts as
+ * a folder's index page.
+ */
+const navStem = (navPath: string): string =>
+  stemOf(navPath.split("/").at(-1) ?? navPath);
+
 interface MutablePage {
   kind: "page";
   key: string;
@@ -79,6 +92,7 @@ interface MutableGroup {
   label: string;
   icon?: string;
   collapsed?: boolean;
+  display?: SidebarDisplay;
   order: number;
   children: MutableNode[];
   index: Map<string, MutableGroup>;
@@ -121,14 +135,17 @@ const ensureGroup = (
   return group;
 };
 
-const pageOrder = (
-  page: PageRecord,
-  filename: string
-): { order: number; orderIsAuthored: boolean } => {
+interface PageOrder {
+  order: number;
+  /** Whether the order came from the author (frontmatter or a rank prefix). */
+  orderIsAuthored: boolean;
+}
+
+const pageOrder = (page: PageRecord, filename: string): PageOrder => {
   if (page.meta.sidebar.order !== undefined) {
     return { order: page.meta.sidebar.order, orderIsAuthored: true };
   }
-  if (isIndexStem(filename.replace(extname(filename), ""))) {
+  if (isIndexStem(stemOf(filename))) {
     return { order: Number.NEGATIVE_INFINITY, orderIsAuthored: false };
   }
   // Changelog entries read newest-first, matching the generated timeline. Sort
@@ -164,18 +181,28 @@ const metaKey = (path: string, metaPrefix: string): string => {
   return path ? `${metaPrefix}/${path}` : metaPrefix;
 };
 
-/** Apply folder meta (title/order/icon/collapsed and explicit page order). */
+/**
+ * Apply folder meta (title/order/icon/collapsed/display and explicit page
+ * order), plus the index-frontmatter display sugar collected per folder path.
+ */
 const applyFolderMeta = (
   group: MutableGroup,
   folderMeta: Map<string, FolderMeta>,
   sharedMeta: Map<string, FolderMeta>,
-  metaPrefix: string
+  metaPrefix: string,
+  sharedMetaPrefix: string,
+  indexDisplay: Map<string, SidebarDisplay>
 ): void => {
   // Locale-specific meta wins; a shared `meta.$.*` (keyed by the locale-stripped
-  // group path) applies to every locale otherwise.
+  // group path — version-prefixed inside a snapshot) applies to every locale
+  // otherwise.
   const meta =
     folderMeta.get(metaKey(group.path, metaPrefix)) ??
-    sharedMeta.get(group.path);
+    sharedMeta.get(metaKey(group.path, sharedMetaPrefix));
+  // The group's own render mode, resolved index frontmatter first, then folder
+  // meta; `toNavNode` falls back to the global mode. Applies to this group
+  // only — nested subgroups resolve their own value through the same chain.
+  group.display = indexDisplay.get(group.path) ?? meta?.display;
   if (meta) {
     group.label = meta.title ?? group.label;
     group.icon = meta.icon ?? group.icon;
@@ -198,7 +225,14 @@ const applyFolderMeta = (
 
   for (const child of group.children) {
     if (child.kind === "group") {
-      applyFolderMeta(child, folderMeta, sharedMeta, metaPrefix);
+      applyFolderMeta(
+        child,
+        folderMeta,
+        sharedMeta,
+        metaPrefix,
+        sharedMetaPrefix,
+        indexDisplay
+      );
     }
   }
 };
@@ -229,14 +263,15 @@ const indexTitleMismatchDiagnostic = (
   folderPath: string,
   folderMeta: Map<string, FolderMeta>,
   sharedMeta: Map<string, FolderMeta>,
-  metaPrefix: string
+  metaPrefix: string,
+  sharedMetaPrefix: string
 ): Diagnostic | undefined => {
   if (!page.meta.title || page.fallback || folderPath === "") {
     return undefined;
   }
   const meta =
     folderMeta.get(metaKey(folderPath, metaPrefix)) ??
-    sharedMeta.get(folderPath);
+    sharedMeta.get(metaKey(folderPath, sharedMetaPrefix));
   if (!meta?.title || meta.title === page.title) {
     return undefined;
   }
@@ -249,6 +284,71 @@ const indexTitleMismatchDiagnostic = (
   };
 };
 
+/**
+ * Warn wherever a page's `sidebar.display` is dead weight, instead of
+ * silently dropping it:
+ *
+ * - On any page under an explicit `navigation.sidebar` config: the config
+ *   items own each group's display mode, and neither index frontmatter nor
+ *   folder meta is read — index pages included.
+ * - On the content root's own index page: the root is not a sidebar group,
+ *   so there is nothing for the value to configure; the sidebar-wide mode
+ *   lives in `navigation.sidebar.display`.
+ * - On any other non-index page: only a folder's index page can configure
+ *   its group's display mode.
+ *
+ * A non-root folder index under the generated sidebar is the one placement
+ * that IS honored, so it alone is exempt. Under i18n fallback fill the same
+ * source file is checked once per locale with an identical message, and the
+ * graph-level code+file+message dedupe collapses the copies.
+ */
+const sidebarDisplayIgnoredDiagnostics = (
+  pages: PageRecord[],
+  explicitSidebar: boolean
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  for (const page of pages) {
+    if (!page.meta.sidebar.display) {
+      continue;
+    }
+    const isIndex = isIndexStem(navStem(page.navPath));
+    if (explicitSidebar) {
+      diagnostics.push({
+        code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
+        file: page.sourcePath ?? page.id,
+        message: `"${page.navPath}" sets sidebar.display, but the explicit navigation.sidebar config owns each group's display mode — the value is ignored.`,
+        severity: "warning",
+        suggestion:
+          "Set display on the matching group in navigation.sidebar, or remove the frontmatter key.",
+      });
+      continue;
+    }
+    if (isIndex && !page.navPath.includes("/")) {
+      diagnostics.push({
+        code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
+        file: page.sourcePath ?? page.id,
+        message: `"${page.navPath}" sets sidebar.display, but the content root is not a sidebar group — the value is ignored.`,
+        severity: "warning",
+        suggestion:
+          "Set navigation.sidebar.display in blume.config to change the sidebar-wide mode.",
+      });
+      continue;
+    }
+    if (isIndex) {
+      continue;
+    }
+    diagnostics.push({
+      code: "BLUME_SIDEBAR_DISPLAY_IGNORED",
+      file: page.sourcePath ?? page.id,
+      message: `"${page.navPath}" sets sidebar.display, but only a folder's index page can set its group's display mode — the value is ignored.`,
+      severity: "warning",
+      suggestion:
+        "Move display to the folder's index page frontmatter, or set it in the folder's meta.ts.",
+    });
+  }
+  return diagnostics;
+};
+
 /** Whether a node's `order` reflects a deliberate authoring choice. */
 const isAuthoredOrder = (node: MutableNode): boolean =>
   node.kind === "group" || node.orderIsAuthored;
@@ -319,20 +419,28 @@ const sortNodes = (nodes: MutableNode[], diagnostics: Diagnostic[]): void => {
 };
 
 /**
- * Hoist loose pages above groups so root-level pages read as top-level entries
- * rather than a group's trailing children (relative order otherwise preserved).
- * All display modes hoist the root level. Flat additionally recurses into every
- * group: there a group renders as a plain section header, so a loose page sorted
- * after a group would visually read as that group's last child.
+ * Hoist loose pages above groups so they read as their own level's entries
+ * rather than a preceding group's trailing children (relative order otherwise
+ * preserved). The root level always hoists, in every display mode. A deeper
+ * level hoists only when a sibling group renders flat — a flat group is a
+ * plain section header, so a loose page sorted after it would visually read
+ * as its last child — while `group`/`page` groups are self-delimiting
+ * disclosure/drill-in rows, so authored interleaving is kept. Each group's
+ * render mode is its own resolved `display` falling back to the global mode,
+ * mirroring `toNavNode`.
  */
-const hoistPages = (nodes: MutableNode[], recurse: boolean): void => {
-  const pages = nodes.filter((node) => node.kind === "page");
+const hoistPages = (
+  nodes: MutableNode[],
+  display: SidebarDisplay,
+  hoist: boolean
+): void => {
   const groups = nodes.filter((node) => node.kind === "group");
-  nodes.splice(0, nodes.length, ...pages, ...groups);
-  if (recurse) {
-    for (const group of groups) {
-      hoistPages(group.children, recurse);
-    }
+  if (hoist || groups.some((group) => (group.display ?? display) === "flat")) {
+    const pages = nodes.filter((node) => node.kind === "page");
+    nodes.splice(0, nodes.length, ...pages, ...groups);
+  }
+  for (const group of groups) {
+    hoistPages(group.children, display, false);
   }
 };
 
@@ -345,16 +453,16 @@ const hoistPages = (nodes: MutableNode[], recurse: boolean): void => {
 const hoistTabSections = (
   nodes: MutableNode[],
   tabPaths: Set<string>,
-  recurse: boolean
+  display: SidebarDisplay
 ): void => {
   for (const node of nodes) {
     if (node.kind !== "group") {
       continue;
     }
     if (node.routePath !== undefined && tabPaths.has(node.routePath)) {
-      hoistPages(node.children, recurse);
+      hoistPages(node.children, display, true);
     }
-    hoistTabSections(node.children, tabPaths, recurse);
+    hoistTabSections(node.children, tabPaths, display);
   }
 };
 
@@ -374,7 +482,7 @@ const toNavNode = (node: MutableNode, display: SidebarDisplay): NavNode => {
   return {
     children: node.children.map((child) => toNavNode(child, display)),
     collapsed: node.collapsed,
-    display,
+    display: node.display ?? display,
     icon: node.icon,
     kind: "group",
     label: node.label,
@@ -388,17 +496,22 @@ const buildFileSystemSidebar = (
   folderMeta: Map<string, FolderMeta>,
   sharedMeta: Map<string, FolderMeta>,
   metaPrefix: string,
+  sharedMetaPrefix: string,
   display: SidebarDisplay,
   tabPaths: Set<string>,
   diagnostics: Diagnostic[] = []
 ): NavNode[] => {
   const root = createGroup("", "", "", 0);
+  // Folder path -> `sidebar.display` from that folder's index page frontmatter.
+  // Collected before the hidden filter (like the title check): hiding the index
+  // row from the panel shouldn't stop it configuring its group.
+  const indexDisplay = new Map<string, SidebarDisplay>();
 
   for (const page of pages) {
     // 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 stem = stemOf(filename);
     const dirs = parts.slice(0, -1);
 
     // Checked before the hidden filter: a sidebar-hidden index page still
@@ -409,11 +522,19 @@ const buildFileSystemSidebar = (
         dirs.join("/"),
         folderMeta,
         sharedMeta,
-        metaPrefix
+        metaPrefix,
+        sharedMetaPrefix
       );
       if (diagnostic) {
         diagnostics.push(diagnostic);
       }
+      // Fallback-filled pages are exempt (like the title check above): their
+      // frontmatter belongs to the fallback locale, and letting it through
+      // would override this locale's own authored `meta.ts` display — then
+      // silently flip again the day the index gets translated.
+      if (page.meta.sidebar.display && !page.fallback) {
+        indexDisplay.set(dirs.join("/"), page.meta.sidebar.display);
+      }
     }
 
     if (page.meta.sidebar.hidden) {
@@ -461,10 +582,17 @@ const buildFileSystemSidebar = (
     });
   }
 
-  applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix);
+  applyFolderMeta(
+    root,
+    folderMeta,
+    sharedMeta,
+    metaPrefix,
+    sharedMetaPrefix,
+    indexDisplay
+  );
   sortNodes(root.children, diagnostics);
-  hoistPages(root.children, display === "flat");
-  hoistTabSections(root.children, tabPaths, display === "flat");
+  hoistPages(root.children, display, true);
+  hoistTabSections(root.children, tabPaths, display);
   return root.children.map((child) => toNavNode(child, display));
 };
 
@@ -498,6 +626,10 @@ const routeForRef = (
   return byRoute.get(normalized)?.route ?? withBasePath(basePath, normalized);
 };
 
+/** An explicit-config sidebar item written as a bare page-ref string. */
+const isPageRef = (item: SidebarItemConfig): item is string =>
+  typeof item === "string";
+
 /**
  * Convert one non-group explicit-config sidebar item (string ref, `root`, or
  * `href`) to a nav node, or null to skip. Group items (`item.items`) are handled
@@ -508,7 +640,7 @@ const configItemToNode = (
   byRoute: Map<string, PageRecord>,
   basePath: string
 ): NavNode | null => {
-  if (typeof item === "string") {
+  if (isPageRef(item)) {
     const page = byRoute.get(normalizeRef(item));
     if (!page) {
       return null;
@@ -561,7 +693,7 @@ const buildConfigSidebar = (
 ): NavNode[] => {
   const nodes: NavNode[] = [];
   for (const item of items) {
-    if (typeof item !== "string" && item.items) {
+    if (!isPageRef(item) && item.items) {
       nodes.push({
         badge: item.badge,
         children: buildConfigSidebar(item.items, byRoute, display, basePath),
@@ -626,6 +758,60 @@ const withTabHrefs = (tabs: NavTab[], sidebar: NavNode[]): NavTab[] =>
     return href === tab.path ? tab : { ...tab, href };
   });
 
+/**
+ * Rebase config-provided nav chrome (featured links, selectors, tabs) under the
+ * site base path. Config paths are authored as if mounted at root, so the base
+ * is applied here (idempotently, and only to internal paths — external URLs
+ * pass through). With no base this is a pure pass-through — the arrays keep
+ * their exact authored shape.
+ */
+interface NavChrome {
+  featured: FeaturedLink[];
+  selectors: NavSelector[];
+  tabs: NavTab[];
+}
+
+const rebaseNavChrome = (
+  basePath: string,
+  options: {
+    featured?: FeaturedLink[];
+    selectors?: NavSelector[];
+    tabs?: NavTab[];
+  }
+): NavChrome => {
+  const featured = options.featured ?? [];
+  const selectors = options.selectors ?? [];
+  const tabs = options.tabs ?? [];
+  if (!basePath) {
+    return { featured, selectors, tabs };
+  }
+  const rebasePath = <T extends { path: string }>(item: T): T => ({
+    ...item,
+    path: withBasePath(basePath, item.path),
+  });
+  return {
+    featured: featured.map((link) => ({
+      ...link,
+      href: withBasePath(basePath, link.href),
+    })),
+    selectors: selectors.map((selector) => ({
+      ...selector,
+      items: selector.items.map(rebasePath),
+    })),
+    tabs: tabs.map((tab) => {
+      const rebased: NavTab = {
+        ...tab,
+        items: tab.items?.map(rebasePath),
+        path: withBasePath(basePath, tab.path),
+      };
+      if (tab.href) {
+        rebased.href = withBasePath(basePath, tab.href);
+      }
+      return rebased;
+    }),
+  };
+};
+
 /** Build the complete navigation model from pages, meta, and config. */
 export const buildNavigation = (
   pages: PageRecord[],
@@ -639,8 +825,18 @@ export const buildNavigation = (
     selectors?: NavSelector[];
     tabs?: NavTab[];
     sidebar?: SidebarItemConfig[];
-    /** Locale dir prefix for folder-meta lookup (`""` for the default locale). */
+    /**
+     * Folder-meta lookup prefix (`""` for the default locale of the current
+     * version): the version dir and/or locale dir hoisted in front of the
+     * group path, e.g. `fr`, `v1.0`, or `v1.0/fr`.
+     */
     metaPrefix?: string;
+    /**
+     * Prefix for shared `meta.$.*` lookups — the version dir inside a
+     * snapshot (`v1.0`), since shared meta is locale-agnostic but still
+     * version-specific. `""` for the current version.
+     */
+    sharedMetaPrefix?: string;
     /**
      * Resolve explicit-sidebar references against each page's locale-agnostic
      * `translationKey` instead of its localized `route`. Used under i18n so a
@@ -667,38 +863,13 @@ export const buildNavigation = (
   const basePath = options.basePath ?? "";
   const display = options.display ?? "flat";
   const metaPrefix = options.metaPrefix ?? "";
+  const sharedMetaPrefix = options.sharedMetaPrefix ?? "";
   const sharedFolderMeta = options.sharedFolderMeta ?? new Map();
 
-  // Config-provided nav paths are authored as if mounted at root, so the base
-  // is applied here (idempotently, and only to internal paths — external URLs
-  // pass through). Content-derived sidebar routes are already based via
-  // `page.route`. The based tab paths also feed tab-scoping below, so they must
-  // agree with the based content routes. With no base, this is a pure pass-
-  // through — the arrays keep their exact authored shape.
-  const rebasePath = <T extends { path: string }>(item: T): T => ({
-    ...item,
-    path: withBasePath(basePath, item.path),
-  });
-  const featured = basePath
-    ? (options.featured ?? []).map((link) => ({
-        ...link,
-        href: withBasePath(basePath, link.href),
-      }))
-    : (options.featured ?? []);
-  const selectors = basePath
-    ? (options.selectors ?? []).map((selector) => ({
-        ...selector,
-        items: selector.items.map(rebasePath),
-      }))
-    : (options.selectors ?? []);
-  const tabs = basePath
-    ? (options.tabs ?? []).map((tab) => ({
-        ...tab,
-        ...(tab.href ? { href: withBasePath(basePath, tab.href) } : {}),
-        items: tab.items?.map(rebasePath),
-        path: withBasePath(basePath, tab.path),
-      }))
-    : (options.tabs ?? []);
+  // Content-derived sidebar routes are already based via `page.route`; the
+  // based tab paths also feed tab-scoping below, so they must agree with the
+  // based content routes.
+  const { featured, selectors, tabs } = rebaseNavChrome(basePath, options);
   const byRoute = new Map(
     pages.map((page) => [
       options.refByLogical ? page.translationKey : page.route,
@@ -727,6 +898,14 @@ export const buildNavigation = (
   // returned navigation so render-time scoping compares in the same space too.
   const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
 
+  // Emitted here, before the sidebar-mode branch: an explicit config sidebar
+  // ignores a stray `sidebar.display` just like the filesystem sidebar does
+  // (and ignores it on index pages too), so both paths must warn.
+  const diagnostics = options.diagnostics ?? [];
+  diagnostics.push(
+    ...sidebarDisplayIgnoredDiagnostics(pages, Boolean(options.sidebar))
+  );
+
   if (options.sidebar) {
     const sidebar = buildConfigSidebar(
       options.sidebar,
@@ -748,11 +927,12 @@ export const buildNavigation = (
     options.folderMeta,
     sharedFolderMeta,
     metaPrefix,
+    sharedMetaPrefix,
     display,
     new Set(
       tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
     ),
-    options.diagnostics
+    diagnostics
   );
   return {
     featured,

package/src/core/probe.ts

@@ -1,3 +1,5 @@
+import pMap from "p-map";
+
 import type { DiagnosticSeverity } from "./types.ts";
 
 export const PROBE_CONCURRENCY = 8;
@@ -113,24 +115,10 @@ export const probeAll = async (
   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
+  const entries = await pMap(
+    unique,
+    async (url) => [url, await probe(url, options)] as const,
+    { concurrency: Math.max(1, options.concurrency ?? PROBE_CONCURRENCY) }
   );
-
-  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;
+  return new Map(entries);
 };

package/src/core/project-graph.ts

@@ -24,6 +24,7 @@ import type {
   PageRecord,
   ProjectContext,
 } from "./types.ts";
+import { versionsDiagnostics } from "./versions.ts";
 
 /** Build mode: drafts are kept in `dev` and dropped in `build`. */
 export type BuildMode = "dev" | "build";
@@ -142,7 +143,7 @@ const entryIdDiagnostics = (
 const normalizeLoadedEntries = (
   loaded: ({ source: ContentSource } & SourceLoadResult)[],
   config: ResolvedConfig
-): { pages: PageRecord[]; diagnostics: Diagnostic[]; droppedPages: number } => {
+) => {
   // Only thread `frontmatter.extend` / `content.types` through when a project
   // opts in, so the known-key split in `normalizeEntry` stays off the default
   // path.
@@ -177,6 +178,7 @@ const normalizeLoadedEntries = (
           staged: source.staged,
         },
         typeFrontmatter,
+        versions: config.versions,
       });
       if (normalized.pages.length === 0 && normalized.diagnostics.length > 0) {
         droppedPages += 1;
@@ -259,7 +261,21 @@ export const scanProject = async (
     Promise.all(
       sources.map(async (source) => ({ source, ...(await source.load()) }))
     ),
-    discoverFolderMeta(metaSources, { localeDirs }),
+    discoverFolderMeta(metaSources, {
+      localeDirs,
+      versionDirs: config.versions?.archived.map((version) => version.id),
+    }),
+  ]);
+
+  // Folder meta contributed by the sources themselves (the OpenAPI source
+  // labels each tag directory with the spec's own tag name). It applies to
+  // every locale, so it merges into the shared map — beneath user-authored
+  // entries, which are spread last and win.
+  const sharedFolderMeta = new Map([
+    ...loaded.flatMap(({ folderMeta: sourceMeta }) =>
+      Object.entries(sourceMeta ?? {})
+    ),
+    ...folderMeta.shared,
   ]);
 
   const {
@@ -301,11 +317,17 @@ export const scanProject = async (
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
-    sharedFolderMeta: folderMeta.shared,
+    sharedFolderMeta,
+    versions: config.versions,
   });
   const manifest = buildManifest({ config, context, graph });
 
-  const i18nWarnings = config.i18n ? i18nDiagnostics(pages, config.i18n) : [];
+  const i18nWarnings = config.i18n
+    ? i18nDiagnostics(pages, config.i18n, config.versions)
+    : [];
+  const versionWarnings = config.versions
+    ? versionsDiagnostics(pages, config.versions)
+    : [];
 
   return {
     config,
@@ -316,6 +338,7 @@ export const scanProject = async (
       ...entryIdDiagnostics(pages, resolveDocsCollection(config, context).base),
       ...graph.diagnostics,
       ...i18nWarnings,
+      ...versionWarnings,
     ],
     droppedPages,
     graph,