blume 1.4.3 → 1.5.1

package/src/core/frontmatter.ts

@@ -14,17 +14,29 @@ type MatterOptions = Parameters<typeof baseMatter>[1];
 type ReadArgs = Parameters<typeof baseMatter.read>;
 type StringifyArgs = Parameters<typeof baseMatter.stringify>;
 
+/** Front matter data as gray-matter types it (`GrayMatterFile["data"]`). */
+type FrontMatterData = ReturnType<typeof baseMatter>["data"];
+
 const yamlEngine = {
+  // SAFETY: gray-matter's engine contract expects an object; a front matter
+  // block is a YAML mapping, and js-yaml returns a scalar only for degenerate
+  // input, which gray-matter treats the same way its bundled engine's output
+  // is treated.
   parse: (input: string): object => (load(input) ?? {}) as object,
-  stringify: (data: object): string => dump(data),
+  stringify: (data: FrontMatterData): string => dump(data),
 };
 
-const withYamlEngine = <O>(options: O): O =>
+const withYamlEngine = <O extends { engines?: object } | undefined>(
+  options: O
+): O =>
+  // SAFETY: the spread keeps every field of `options`; adding a default yaml
+  // engine (overridden by any caller-supplied `engines`) stays within O's
+  // shape — TS just can't prove a spread of a generic re-satisfies O.
   ({
     ...options,
     engines: {
       yaml: yamlEngine,
-      ...(options as { engines?: object })?.engines,
+      ...options?.engines,
     },
   }) as O;
 
@@ -52,13 +64,21 @@ const opensWithThematicBreak = (input: string): boolean => {
   return !input.includes("\n---", 1);
 };
 
+/**
+ * gray-matter's runtime result carries `isEmpty`, which its declared
+ * GrayMatterFile type omits.
+ */
+interface MatterResult extends ReturnType<typeof baseMatter> {
+  isEmpty: boolean;
+}
+
 /**
  * The parse result for a document with no front matter: the input passes
  * through as content, untouched. Shaped like gray-matter's own no-matter
  * result (every Blume call site reads only `content` and `data`).
  */
-const passthrough = (input: string): ReturnType<typeof baseMatter> =>
-  ({
+const passthrough = (input: string): ReturnType<typeof baseMatter> => {
+  const file: MatterResult = {
     content: input,
     data: {},
     excerpt: "",
@@ -68,7 +88,13 @@ const passthrough = (input: string): ReturnType<typeof baseMatter> =>
     orig: input,
     // Recomposing a file with no matter and empty data is the content itself.
     stringify: (): string => input,
-  }) as unknown as ReturnType<typeof baseMatter>;
+  };
+  return file;
+};
+
+/** Narrows gray-matter's input union to the raw-string form. */
+const isStringInput = (input: MatterInput): input is string =>
+  typeof input === "string";
 
 // Every helper that parses or emits YAML (`read`, `stringify`) must be
 // re-wrapped here — Object.assign copies gray-matter's own helpers, which use
@@ -76,7 +102,7 @@ const passthrough = (input: string): ReturnType<typeof baseMatter> =>
 // checks for a delimiter, so the copied original is safe.
 const matter = Object.assign(
   (input: MatterInput, options?: MatterOptions) =>
-    typeof input === "string" && opensWithThematicBreak(input)
+    isStringInput(input) && opensWithThematicBreak(input)
       ? passthrough(input)
       : baseMatter(input, withYamlEngine(options)),
   baseMatter,

package/src/core/graph.ts

@@ -7,6 +7,7 @@ import type {
   LocalizableLabel,
   ResolvedConfig,
   ResolvedI18nConfig,
+  ResolvedVersionsConfig,
 } from "./schema.ts";
 import type {
   ContentGraph,
@@ -15,6 +16,7 @@ import type {
   NavTab,
   PageRecord,
 } from "./types.ts";
+import { versionizeRoute } from "./versions.ts";
 
 interface BuildContentGraphOptions {
   /** Site-wide route mount point (`""` or `/seg`); invisible to the nav tree. */
@@ -23,14 +25,13 @@ interface BuildContentGraphOptions {
   sharedFolderMeta?: Map<string, FolderMeta>;
   navigation: ResolvedConfig["navigation"];
   i18n?: ResolvedI18nConfig;
+  versions?: ResolvedVersionsConfig;
 }
 
 type FallbackLocale = ReturnType<typeof resolveFallbackLocale>;
 
 /** Build the route → page-id map, flagging any duplicate-route collisions. */
-const collectRoutes = (
-  pages: PageRecord[]
-): { diagnostics: Diagnostic[]; routes: Map<string, string> } => {
+const collectRoutes = (pages: PageRecord[]) => {
   const routes = new Map<string, string>();
   const diagnostics: Diagnostic[] = [];
   for (const page of pages) {
@@ -86,12 +87,16 @@ const localePagesFor = (
  * the active locale's entry, else the default locale's, else the map's first
  * entry (which is also what a single-locale site gets).
  */
+/** A label is either one string for every locale or a per-locale map. */
+const isSingleLabel = (label: LocalizableLabel): label is string =>
+  typeof label === "string";
+
 const resolveLabel = (
   label: LocalizableLabel,
   locale: string,
   defaultLocale?: string
 ): string => {
-  if (typeof label === "string") {
+  if (isSingleLabel(label)) {
     return label;
   }
   return (
@@ -117,7 +122,12 @@ const resolveTabLabels = (
     label: resolveLabel(tab.label, locale, defaultLocale),
   }));
 
-/** Build one locale's navigation tree from its own pages and folder meta. */
+/**
+ * Build one locale's navigation tree from its own pages and folder meta.
+ * `version` is the archived version id when building a snapshot's tree
+ * (`""` for the current docs): it shifts the folder-meta lookups into the
+ * snapshot's key space and roots the tree at the localized version root.
+ */
 const buildLocaleNavigation = (
   code: string,
   pages: PageRecord[],
@@ -125,7 +135,8 @@ const buildLocaleNavigation = (
   fallbackByKey: Map<string, PageRecord>,
   options: BuildContentGraphOptions,
   i18n: ResolvedI18nConfig,
-  diagnostics: Diagnostic[]
+  diagnostics: Diagnostic[],
+  version = ""
 ): Navigation => {
   // Localize internal tab paths — the tab's own and its dropdown items' — so a
   // header tab points to its in-locale route (e.g. `/docs` -> `/fr/docs`);
@@ -137,15 +148,20 @@ const buildLocaleNavigation = (
     options.navigation.tabs,
     code,
     i18n.defaultLocale
-  ).map((tab) => ({
-    ...tab,
-    ...(tab.href ? { href: localizePath(tab.href) } : {}),
-    items: tab.items?.map((item) => ({
-      ...item,
-      path: localizePath(item.path),
-    })),
-    path: localizePath(tab.path),
-  }));
+  ).map((tab) => {
+    const localized = {
+      ...tab,
+      items: tab.items?.map((item) => ({
+        ...item,
+        path: localizePath(item.path),
+      })),
+      path: localizePath(tab.path),
+    };
+    if (localized.href) {
+      localized.href = localizePath(localized.href);
+    }
+    return localized;
+  });
   const real = pages.filter((page) => page.locale === code);
   const localePages = localePagesFor(
     code,
@@ -155,6 +171,13 @@ const buildLocaleNavigation = (
     i18n,
     options.basePath ?? ""
   );
+  // Meta files live in locale directories only under the `dir` parser
+  // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations sit
+  // next to the originals and `guides/meta.ts` applies to every locale —
+  // prefixing would look up keys that can never exist. Inside a snapshot the
+  // version dir is hoisted in front (`v1.0/fr`), matching `discoverFolderMeta`.
+  const localeDir =
+    i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "";
   return buildNavigation(localePages, {
     basePath: options.basePath ?? "",
     diagnostics,
@@ -167,34 +190,37 @@ const buildLocaleNavigation = (
       href: localizePath(link.href),
     })),
     folderMeta: options.folderMeta,
-    // The localized tree root ("/" for the hidden default, "/fr" otherwise):
-    // the tab pointing here spans the whole tree and must not be treated as a
-    // tab section.
-    localizedRoot: localizeRoute("/", code, i18n),
-    // Meta files live in locale directories only under the `dir` parser
-    // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations sit
-    // next to the originals and `guides/meta.ts` applies to every locale —
-    // prefixing would look up keys that can never exist.
-    metaPrefix:
-      i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "",
+    // The localized tree root ("/" for the hidden default, "/fr" otherwise;
+    // "/fr/v1.0" inside a snapshot): the tab pointing here spans the whole
+    // tree and must not be treated as a tab section.
+    localizedRoot: localizeRoute(versionizeRoute("/", version), code, i18n),
+    metaPrefix: [version, localeDir].filter(Boolean).join("/"),
     refByLogical: true,
     selectors: options.navigation.selectors,
     sharedFolderMeta: options.sharedFolderMeta,
-    sidebar: options.navigation.sidebar.items,
+    // Shared `meta.$.*` files are locale-agnostic but version-specific: a
+    // snapshot's shared meta keys under its version dir.
+    sharedMetaPrefix: version,
+    // A configured explicit sidebar describes the current docs; a frozen
+    // snapshot's structure comes from the snapshot itself, so archived trees
+    // always build from the filesystem.
+    sidebar: version ? undefined : options.navigation.sidebar.items,
     tabs,
   });
 };
 
-/** Per-locale navigation trees plus the default-locale tree for i18n sites. */
+/**
+ * Per-locale navigation trees plus the default-locale tree for i18n sites.
+ * Called once for the current docs and once per archived version (with that
+ * version's pages and its id as `version`).
+ */
 const buildI18nNavigation = (
   pages: PageRecord[],
   options: BuildContentGraphOptions,
   i18n: ResolvedI18nConfig,
-  diagnostics: Diagnostic[]
-): {
-  navigation: Navigation;
-  navigationByLocale: Record<string, Navigation>;
-} => {
+  diagnostics: Diagnostic[],
+  version = ""
+) => {
   // Pages of the fallback locale, by translation key — used to fill in a
   // locale's sidebar for pages it hasn't translated yet.
   const fallback = resolveFallbackLocale(i18n);
@@ -223,7 +249,8 @@ const buildI18nNavigation = (
       fallbackByKey,
       options,
       i18n,
-      localeDiagnostics
+      localeDiagnostics,
+      version
     );
     for (const diagnostic of localeDiagnostics) {
       const key = `${diagnostic.code}\n${diagnostic.file ?? ""}\n${diagnostic.message}`;
@@ -233,7 +260,7 @@ const buildI18nNavigation = (
       }
     }
   }
-  const navigation = navigationByLocale[i18n.defaultLocale] ?? {
+  const navigation: Navigation = navigationByLocale[i18n.defaultLocale] ?? {
     featured: [],
     selectors: [],
     sidebar: [],
@@ -242,6 +269,37 @@ const buildI18nNavigation = (
   return { navigation, navigationByLocale };
 };
 
+/** One archived version's navigation trees, keyed by locale (`""` sans i18n). */
+const buildVersionNavigation = (
+  id: string,
+  versionPages: PageRecord[],
+  options: BuildContentGraphOptions,
+  diagnostics: Diagnostic[]
+) => {
+  const { i18n } = options;
+  if (i18n) {
+    return buildI18nNavigation(versionPages, options, i18n, diagnostics, id)
+      .navigationByLocale;
+  }
+  return {
+    "": buildNavigation(versionPages, {
+      basePath: options.basePath ?? "",
+      diagnostics,
+      display: options.navigation.sidebar.display,
+      featured: options.navigation.featured,
+      folderMeta: options.folderMeta,
+      localizedRoot: versionizeRoute("/", id),
+      metaPrefix: id,
+      selectors: options.navigation.selectors,
+      sharedFolderMeta: options.sharedFolderMeta,
+      sharedMetaPrefix: id,
+      // A configured explicit sidebar describes the current docs; a snapshot's
+      // structure comes from the snapshot itself.
+      tabs: resolveTabLabels(options.navigation.tabs, ""),
+    }),
+  };
+};
+
 /** Assemble the content graph: routes map, nav, and duplicate diagnostics. */
 export const buildContentGraph = (
   pages: PageRecord[],
@@ -250,37 +308,63 @@ export const buildContentGraph = (
   const { diagnostics, routes } = collectRoutes(pages);
   const { i18n } = options;
 
-  const { navigation, navigationByLocale } = i18n
-    ? buildI18nNavigation(pages, options, i18n, diagnostics)
-    : {
-        navigation: buildNavigation(pages, {
-          basePath: options.basePath ?? "",
-          diagnostics,
-          display: options.navigation.sidebar.display,
-          featured: options.navigation.featured,
-          folderMeta: options.folderMeta,
-          selectors: options.navigation.selectors,
-          sharedFolderMeta: options.sharedFolderMeta,
-          sidebar: options.navigation.sidebar.items,
-          // No locale to prefer: a per-locale label map resolves to its first
-          // entry on a single-locale site.
-          tabs: resolveTabLabels(options.navigation.tabs, ""),
-        }),
-        navigationByLocale: {} as Record<string, Navigation>,
-      };
+  // Under versioning, each version gets independent trees: navPath is
+  // version-stripped, so mixing versions into one build would collide the
+  // same logical page once per version.
+  const currentPages = options.versions
+    ? pages.filter((page) => page.version === "")
+    : pages;
+
+  // A single-locale site has no per-locale trees; the empty map is its
+  // navigationByLocale.
+  let navigationByLocale: Record<string, Navigation> = {};
+  let navigation: Navigation;
+  if (i18n) {
+    ({ navigation, navigationByLocale } = buildI18nNavigation(
+      currentPages,
+      options,
+      i18n,
+      diagnostics
+    ));
+  } else {
+    navigation = buildNavigation(currentPages, {
+      basePath: options.basePath ?? "",
+      diagnostics,
+      display: options.navigation.sidebar.display,
+      featured: options.navigation.featured,
+      folderMeta: options.folderMeta,
+      selectors: options.navigation.selectors,
+      sharedFolderMeta: options.sharedFolderMeta,
+      sidebar: options.navigation.sidebar.items,
+      // No locale to prefer: a per-locale label map resolves to its first
+      // entry on a single-locale site.
+      tabs: resolveTabLabels(options.navigation.tabs, ""),
+    });
+  }
+
+  const navigationByVersion: Record<string, Record<string, Navigation>> = {};
+  for (const { id } of options.versions?.archived ?? []) {
+    navigationByVersion[id] = buildVersionNavigation(
+      id,
+      pages.filter((page) => page.version === id),
+      options,
+      diagnostics
+    );
+  }
 
   // Icon typos, duplicate labels, and hidden-page-in-sidebar are validated on
   // the built navigation. Missing-target detection needs the full route set
   // (incl. custom + generated pages), so it runs later in generateRuntime.
   diagnostics.push(
     ...validateNavIcons(navigation),
-    ...validateNavStructure(navigation, pages)
+    ...validateNavStructure(navigation, currentPages)
   );
 
   return {
     diagnostics,
     navigation,
     navigationByLocale,
+    navigationByVersion,
     pages,
     routes,
   };

package/src/core/i18n-ui.ts

@@ -123,6 +123,7 @@ const uiStringsObject = z.object({
     .object({
       all: z.string().default("All"),
       allLanguages: z.string().default("All languages"),
+      allVersions: z.string().default("All versions"),
       askAi: z.string().default("Ask AI"),
       askAiHint: z.string().default("Get an instant answer from AI"),
       button: z.string().default("Search"),
@@ -145,6 +146,18 @@ const uiStringsObject = z.object({
       title: z.string().default("On this page"),
     })
     .prefault({}),
+  versions: z
+    .object({
+      latest: z.string().default("Go to latest"),
+      // `{version}` is replaced with the archived version's label at render time.
+      notice: z
+        .string()
+        .default(
+          "You're viewing documentation for {version}. It may be out of date."
+        ),
+      switcher: z.string().default("Version"),
+    })
+    .prefault({}),
 });
 
 export const uiStringsSchema = uiStringsObject.prefault({});
@@ -186,6 +199,8 @@ const mergeUI = (base: UIStrings, override?: UIStringsOverride): UIStrings => {
   }
   const out: UIStrings = structuredClone(base);
   for (const [group, values] of Object.entries(override)) {
+    // SAFETY: UIStrings is exactly two levels of string leaves, and the
+    // override schema mirrors its groups, so `group` indexes a string map.
     const target = (out as Record<string, Record<string, string>>)[group];
     if (target && values) {
       Object.assign(target, values);

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/last-modified.ts

@@ -2,6 +2,8 @@ import { execFileSync } from "node:child_process";
 
 import { relative } from "pathe";
 
+import type { Diagnostic } from "./types.ts";
+
 /** Normalized form of the `lastModified` config. */
 export interface ResolvedLastModified {
   enabled: boolean;
@@ -95,3 +97,50 @@ export const gitLastModifiedTimes = (
     return new Map();
   }
 };
+
+/**
+ * Whether the repository containing `root` is a shallow clone. Returns false
+ * when git is unavailable or the project isn't a repo — those cases already
+ * yield no dates at all, and the shallow warning would only mislead.
+ */
+export const isShallowGitRepository = (root: string): boolean => {
+  try {
+    return (
+      execFileSync(
+        // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
+        "git",
+        ["-C", root, "rev-parse", "--is-shallow-repository"],
+        // stderr silenced: outside a repository the probe fails by design.
+        { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
+      ).trim() === "true"
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * A warning for git-derived dates silently missing because the build ran in a
+ * shallow clone — the default on Vercel and `actions/checkout`, where `git log`
+ * only sees the last few commits, so most pages get no date and the sitemap's
+ * `<lastmod>` / "Last updated" stamps quietly disappear in production while
+ * working locally. Empty when every page got a date or the clone isn't
+ * shallow.
+ */
+export const lastModifiedShallowWarning = (
+  root: string,
+  undatedCount: number
+): Diagnostic[] => {
+  if (undatedCount === 0 || !isShallowGitRepository(root)) {
+    return [];
+  }
+  return [
+    {
+      code: "BLUME_SHALLOW_GIT_HISTORY",
+      message: `lastModified is on, but this build runs in a shallow git clone, so ${undatedCount} page(s) have no git-derived date — their sitemap <lastmod> and "Last updated" stamps are omitted.`,
+      severity: "warning",
+      suggestion:
+        "Fetch full history in CI: set the VERCEL_DEEP_CLONE=true environment variable on Vercel, or fetch-depth: 0 for actions/checkout.",
+    },
+  ];
+};

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) => {