blume 1.4.2 → 1.5.0

package/src/core/i18n.ts

@@ -1,4 +1,8 @@
-import type { ResolvedConfig, ResolvedI18nConfig } from "./schema.ts";
+import type {
+  ResolvedConfig,
+  ResolvedI18nConfig,
+  ResolvedVersionsConfig,
+} from "./schema.ts";
 import type { Diagnostic, PageRecord } from "./types.ts";
 import { UI_PACKS } from "./ui-packs/index.ts";
 
@@ -70,10 +74,7 @@ export const localizeRoute = (
  * matched as a leading segment. Returns the resolved locale and the remaining
  * (locale-stripped) segments.
  */
-export const detectLocale = (
-  parts: string[],
-  i18n: ResolvedI18nConfig
-): { locale: string; rest: string[] } => {
+export const detectLocale = (parts: string[], i18n: ResolvedI18nConfig) => {
   // BCP 47 codes are case-insensitive: a conventional lowercase folder
   // (`pt-br/`) must match a configured `pt-BR`. The configured casing is what
   // flows into routes and labels.
@@ -102,7 +103,7 @@ export const localePlacement = (
   rel: string,
   ext: string,
   i18n: ResolvedI18nConfig
-): { navPath: string; locales: string[] } => {
+) => {
   const base = rel.slice(0, rel.length - ext.length);
 
   // Shared `$` file: the same content in every locale. A shared file placed
@@ -187,17 +188,24 @@ export const localeTargetPath = (
  */
 export const i18nDiagnostics = (
   pages: PageRecord[],
-  i18n: ResolvedI18nConfig
+  i18n: ResolvedI18nConfig,
+  versions?: ResolvedVersionsConfig
 ): Diagnostic[] => {
   const configured = new Set(
     i18n.locales.map((locale) => locale.code.toLowerCase())
   );
+  const versionDirs = new Set(versions?.archived.map((version) => version.id));
   const seen = new Set<string>();
   const diagnostics: Diagnostic[] = [];
   for (const page of pages) {
     // The locale-looking folder is the first segment of the source-local ref
     // (e.g. `fr/guide.md`), not the namespaced id (`filesystem:fr/guide.md`).
-    const first = page.source.ref.split("/")[0]?.toLowerCase();
+    // Inside a version snapshot the locale dir sits one level deeper
+    // (`v1.0/fr/guide.md`), so a configured version segment is skipped first.
+    const parts = page.source.ref.split("/");
+    const first = (
+      parts[0] && versionDirs.has(parts[0]) ? parts[1] : parts[0]
+    )?.toLowerCase();
     if (
       first &&
       !seen.has(first) &&

package/src/core/load-module.ts

@@ -6,6 +6,7 @@ import { createJiti } from "jiti";
  * is called with. `moduleCache: false` ensures edits are picked up on each load,
  * which is what makes dev-server regeneration reflect config/meta changes.
  */
+// oxlint-disable-next-line anti-slop/no-unknown-returns -- user-authored modules can export anything; callers validate the loaded value at their own boundary
 export const createModuleLoader = (): ((file: string) => Promise<unknown>) => {
   const jiti = createJiti(import.meta.url, { moduleCache: false });
   return async (file: string) => {

package/src/core/manifest.ts

@@ -8,9 +8,39 @@ import type {
   ProjectContext,
   RouteAlternate,
   RouteManifestEntry,
+  VersionAlternate,
 } from "./types.ts";
 import { getBlumeVersion } from "./version.ts";
 
+/**
+ * Key for the same logical page across versions within one locale: the
+ * version- and locale-agnostic route plus the locale code. NUL never appears
+ * in either part, so the join is unambiguous.
+ */
+const versionAlternateKey = (versionKey: string, locale: string): string =>
+  `${versionKey}\u0000${locale}`;
+
+/**
+ * Get-or-create the shared alternate list for a (versionKey, locale) pair.
+ * Lists are attached to route entries by reference and mutated as fallback
+ * routes materialize, then sorted once at the end — every holder sees the
+ * final list.
+ */
+const versionAlternatesFor = (
+  byKey: Map<string, VersionAlternate[]>,
+  versionKey: string,
+  locale: string
+): VersionAlternate[] => {
+  const key = versionAlternateKey(versionKey, locale);
+  const existing = byKey.get(key);
+  if (existing) {
+    return existing;
+  }
+  const list: VersionAlternate[] = [];
+  byKey.set(key, list);
+  return list;
+};
+
 /** The current manifest schema version. */
 export const MANIFEST_VERSION = 1;
 
@@ -37,7 +67,8 @@ const buildFallbackRoutes = (
   graph: ContentGraph,
   i18n: NonNullable<ResolvedConfig["i18n"]>,
   alternatesByKey: Map<string, RouteAlternate[]>,
-  basePath: string
+  basePath: string,
+  versionAlternatesByKey: Map<string, VersionAlternate[]> | undefined
 ): RouteManifestEntry[] => {
   const fallback = resolveFallbackLocale(i18n);
   if (!fallback) {
@@ -62,6 +93,17 @@ const buildFallbackRoutes = (
       if (present.has(key)) {
         continue;
       }
+      const path = withBasePath(basePath, localizeRoute(key, code, i18n));
+      // A fallback route is a real prerendered page, so it registers as a
+      // version alternate too — the switcher on a sibling version's page
+      // lands here instead of bouncing to the version root. Its own path is
+      // recorded (not the fallback source's), keeping the target in-locale.
+      const versionAlternates: VersionAlternate[] = versionAlternatesByKey
+        ? versionAlternatesFor(versionAlternatesByKey, source.versionKey, code)
+        : [];
+      if (versionAlternatesByKey) {
+        versionAlternates.push({ path, version: source.version });
+      }
       routes.push({
         alternates: alternatesByKey.get(key) ?? [],
         collection: source.collection ?? "docs",
@@ -75,10 +117,12 @@ const buildFallbackRoutes = (
         indexable: false,
         lastModified: source.lastModified,
         locale: code,
-        path: withBasePath(basePath, localizeRoute(key, code, i18n)),
+        path,
         source: source.source,
         sourcePath: source.sourcePath,
         title: source.title,
+        version: source.version,
+        versionAlternates,
       });
     }
   }
@@ -106,6 +150,23 @@ export const buildManifest = (options: {
     }
   }
 
+  // The same logical page across versions, within each locale — for the
+  // version switcher and the canonical-to-latest lookup. Built only under
+  // versioning; lists are shared by reference and finalized (fallback routes
+  // appended, then sorted) before the manifest is returned.
+  const versionAlternatesByKey = config.versions
+    ? new Map<string, VersionAlternate[]>()
+    : undefined;
+  if (versionAlternatesByKey) {
+    for (const page of graph.pages) {
+      versionAlternatesFor(
+        versionAlternatesByKey,
+        page.versionKey,
+        page.locale
+      ).push({ path: page.route, version: page.version });
+    }
+  }
+
   const routes: RouteManifestEntry[] = graph.pages.map((page) => ({
     alternates: alternatesByKey.get(page.translationKey) ?? [],
     collection: page.collection ?? "docs",
@@ -122,14 +183,42 @@ export const buildManifest = (options: {
     source: page.source,
     sourcePath: page.sourcePath,
     title: page.title,
+    version: page.version,
+    versionAlternates: versionAlternatesByKey
+      ? versionAlternatesFor(
+          versionAlternatesByKey,
+          page.versionKey,
+          page.locale
+        )
+      : [],
   }));
 
   if (i18n) {
     routes.push(
-      ...buildFallbackRoutes(graph, i18n, alternatesByKey, config.basePath)
+      ...buildFallbackRoutes(
+        graph,
+        i18n,
+        alternatesByKey,
+        config.basePath,
+        versionAlternatesByKey
+      )
     );
   }
 
+  // Alternate lists read current-first, then archived versions in configured
+  // (switcher) order. Sorted once here — every route holding a list by
+  // reference sees the final ordering.
+  if (versionAlternatesByKey && config.versions) {
+    const rank = new Map<string, number>(
+      config.versions.archived.map((version, index) => [version.id, index + 1])
+    );
+    for (const list of versionAlternatesByKey.values()) {
+      list.sort(
+        (a, b) => (rank.get(a.version) ?? 0) - (rank.get(b.version) ?? 0)
+      );
+    }
+  }
+
   routes.sort((a, b) => a.path.localeCompare(b.path));
 
   return {

package/src/core/meta.ts

@@ -17,9 +17,23 @@ const META_FILES = [
   "**/meta.$.mjs",
 ];
 
+/**
+ * A meta module's default export before validation: `folderMetaSchema` parses
+ * it only after any factory is resolved, so it carries the loader's raw type.
+ */
+type MetaModuleExport = Awaited<
+  ReturnType<ReturnType<typeof createModuleLoader>>
+>;
+
+/** A factory-style meta module default-exports a function returning the meta. */
+const isMetaFactory = (
+  mod: MetaModuleExport
+): mod is () => MetaModuleExport | Promise<MetaModuleExport> =>
+  typeof mod === "function";
+
 /** Resolve a meta module's default export, calling it if it is a factory. */
-const resolveMeta = async (mod: unknown): Promise<unknown> =>
-  typeof mod === "function" ? await (mod as () => unknown)() : mod;
+const resolveMeta = async (mod: MetaModuleExport) =>
+  isMetaFactory(mod) ? await mod() : mod;
 
 /** A filesystem content source to scan for folder meta: its on-disk root and
  * optional route prefix. The prefix is folded into every key so meta lines up
@@ -58,18 +72,28 @@ const metaKeyFor = (prefix: string | undefined, dir: string): string => {
  * group path starts with the source prefix, so a locale directory found at a
  * source root is hoisted in front of the prefix (`docs/fr/guides/meta.ts` keys
  * to `fr/docs/guides`, not `docs/fr/guides`).
+ *
+ * `versionDirs` names the archived-version snapshot directories, which sit
+ * outermost on disk — a locale directory inside a snapshot is one level deeper.
+ * Both are hoisted, version first (`v1.0/fr/guides/meta.ts` keys to
+ * `v1.0/fr/<prefix>/guides`), matching navigation's version-aware meta prefix.
  */
 export const discoverFolderMeta = async (
   sources: string | FolderMetaSource[],
-  options: { localeDirs?: readonly string[] } = {}
+  options: {
+    localeDirs?: readonly string[];
+    versionDirs?: readonly string[];
+  } = {}
 ): Promise<{
   meta: Map<string, FolderMeta>;
   shared: Map<string, FolderMeta>;
   diagnostics: Diagnostic[];
 }> => {
-  const list: FolderMetaSource[] =
-    typeof sources === "string" ? [{ root: sources }] : sources;
+  const list: FolderMetaSource[] = Array.isArray(sources)
+    ? sources
+    : [{ root: sources }];
   const localeDirs = new Set(options.localeDirs);
+  const versionDirs = new Set(options.versionDirs);
 
   const load = createModuleLoader();
   const meta = new Map<string, FolderMeta>();
@@ -103,6 +127,8 @@ export const discoverFolderMeta = async (
                 value: await resolveMeta(await load(file)),
               };
             } catch (error) {
+              // SAFETY: jiti surfaces load/evaluate failures as Error
+              // instances, and only `message` is read downstream.
               return { error: error as Error, file, ok: false };
             }
           }
@@ -115,16 +141,20 @@ export const discoverFolderMeta = async (
   for (const { loaded, source } of perSource) {
     for (const entry of loaded) {
       const dir = relative(source.root, dirname(entry.file));
+      // A version snapshot dir is outermost, with a locale dir one level
+      // deeper; both are hoisted in front of the (prefixed) group path, in
+      // that order — the lookup key reads `version/locale/prefix/dir`.
       const [head, ...tail] = dir.split("/");
-      // A locale directory sits between the source root and the folder, but the
-      // lookup key carries the locale in front of the (prefixed) group path.
-      const key =
-        head && localeDirs.has(head)
-          ? `${head}/${metaKeyFor(source.prefix, tail.join("/"))}`.replace(
-              /\/$/u,
-              ""
-            )
-          : metaKeyFor(source.prefix, dir);
+      const version = head && versionDirs.has(head) ? head : "";
+      const afterVersion = version ? tail : [head ?? "", ...tail];
+      const [localeHead, ...localeTail] = afterVersion;
+      const locale = localeHead && localeDirs.has(localeHead) ? localeHead : "";
+      const rest = (locale ? localeTail : afterVersion)
+        .filter(Boolean)
+        .join("/");
+      const key = [version, locale, metaKeyFor(source.prefix, rest)]
+        .filter(Boolean)
+        .join("/");
 
       if (!entry.ok) {
         diagnostics.push({

package/src/core/nav-diagnostics.ts

@@ -9,7 +9,7 @@ import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
  * covers every source (config, folder meta, frontmatter) at once.
  */
 
-const ICON_SHAPE_HINT =
+const ICON_FORMAT_HINT =
   "Use a built-in icon name, an image path/URL, or inline SVG markup.";
 
 /** Flatten a sidebar tree to every node, descending into groups. */
@@ -80,7 +80,7 @@ const unknownIconDiagnostics = (
 
 /** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
 export const validateNavIcons = (navigation: Navigation): Diagnostic[] =>
-  unknownIconDiagnostics(collectIcons(navigation), ICON_SHAPE_HINT);
+  unknownIconDiagnostics(collectIcons(navigation), ICON_FORMAT_HINT);
 
 /**
  * Warn about unknown icons on curated `search.popular` links. Same accepted
@@ -94,7 +94,7 @@ export const validateSearchPopularIcons = (
       ? [{ icon: link.icon, where: `popular link "${link.label}"` }]
       : []
   );
-  return unknownIconDiagnostics(icons, ICON_SHAPE_HINT);
+  return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
 };
 
 /** Whether an internal path resolves to a page or a section that has pages. */