blume 0.6.7 → 0.7.0

package/src/core/i18n-ui.ts

@@ -96,8 +96,23 @@ export const uiStringsSchema = uiStringsObject.default({});
 /** A fully-resolved dictionary; every key present. */
 export type UIStrings = z.infer<typeof uiStringsObject>;
 
-/** The English baseline, derived from the schema defaults. */
-export const EN_UI: UIStrings = uiStringsObject.parse({});
+/**
+ * The English baseline, derived from the schema defaults.
+ *
+ * Each group is passed explicitly as `{}` rather than parsing a bare `{}`: a
+ * group's `.default({})` only re-applies its inner field defaults when the group
+ * is *present but empty*. Zod 4 changed `.default()` to return the literal
+ * default value without re-parsing it through the inner type, so a bare
+ * `parse({})` leaves every group undefined and collapses each to `{}` there.
+ * Because these components resolve Zod from the consuming project — which may be
+ * on v4 while the CLI bundles v3 — the runtime baseline would silently render
+ * blank (empty search labels, aria-labels, skip link). Naming every group keeps
+ * the baseline fully populated on both Zod 3 and 4.
+ */
+const EN_UI_INPUT: Record<string, unknown> = Object.fromEntries(
+  Object.keys(uiStringsObject.shape).map((group) => [group, {}])
+);
+export const EN_UI: UIStrings = uiStringsObject.parse(EN_UI_INPUT);
 
 /**
  * A partial override: `{ group: { key: "translation" } }`. Validated loosely
@@ -138,7 +153,7 @@ const mergeUI = (base: UIStrings, override?: UIStringsOverride): UIStrings => {
  * pack so adopters get translated chrome out of the box. Re-exported here so the
  * resolver and existing imports keep a single entry point.
  */
-export { UI_PACKS };
+export { UI_PACKS } from "./ui-packs/index.ts";
 
 /** Case-insensitive index for region-variant lookup (`pt-br` -> `pt-BR`). */
 const PACKS_BY_LOWER: Record<string, UIStringsOverride> = Object.fromEntries(

package/src/core/last-modified.ts

@@ -54,11 +54,13 @@ export const gitLastModifiedTimes = (
 ): Map<string, string> => {
   try {
     const gitRoot = 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", "--show-toplevel"],
       { encoding: "utf-8" }
     ).trim();
     const output = execFileSync(
+      // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
       "git",
       [
         "-C",

package/src/core/links.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 
 import { basename, join } from "pathe";
 
+import { stripBasePath, withBasePath } from "./base-path.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -46,6 +47,8 @@ interface ExternalRef extends LinkSite {
 /** Lookups derived once from the content graph. */
 interface LinkContext {
   anchors: Map<string, Set<string>>;
+  /** Site-wide route mount point (`""` or `/seg`); routes carry it, assets don't. */
+  basePath: string;
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
@@ -70,6 +73,18 @@ const isIndexPage = (page: PageRecord): boolean => {
   return /^index\.(?:md|mdx)$/iu.test(basename(ref));
 };
 
+/** Apply one relative-path segment to the accumulated route segments. */
+const applyRelativePart = (segments: string[], part: string): void => {
+  if (part === "" || part === ".") {
+    return;
+  }
+  if (part === "..") {
+    segments.pop();
+    return;
+  }
+  segments.push(part);
+};
+
 /** Resolve a relative link target against the directory of a page route. */
 const resolveRelative = (
   pageRoute: string,
@@ -83,14 +98,7 @@ const resolveRelative = (
     segments.pop();
   }
   for (const part of target.split("/")) {
-    if (part === "" || part === ".") {
-      continue;
-    }
-    if (part === "..") {
-      segments.pop();
-      continue;
-    }
-    segments.push(part);
+    applyRelativePart(segments, part);
   }
   return `/${segments.join("/")}`;
 };
@@ -145,10 +153,12 @@ const checkPathLink = (
   site: LinkSite,
   ctx: LinkContext
 ): LinkResult => {
-  // A real route always wins over the asset-extension heuristic, so a path
-  // whose last segment merely contains a dot (e.g. a page at `/releases/v1.0`)
-  // isn't misread as a missing asset.
-  const route = toRoute(resolved);
+  // Page routes carry the site-wide base; an absolute author path is written
+  // as if mounted at root, so base it for the route lookup (idempotent — a
+  // relative link already resolved against the based `page.route`). A real
+  // route always wins over the asset-extension heuristic, so a dotted route
+  // (e.g. `/releases/v1.0`) isn't misread as a missing asset.
+  const route = toRoute(withBasePath(ctx.basePath, resolved));
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx) : null;
   }
@@ -159,8 +169,11 @@ const checkPathLink = (
     return null;
   }
 
-  if (FILE_EXT.test(resolved) && !DOC_EXT.test(resolved)) {
-    if (assetIsPresent(resolved, ctx)) {
+  // Assets live in `public/` at the site root, unaffected by the base, so strip
+  // it back off before probing the filesystem.
+  const assetPath = stripBasePath(ctx.basePath, resolved);
+  if (FILE_EXT.test(assetPath) && !DOC_EXT.test(assetPath)) {
+    if (assetIsPresent(assetPath, ctx)) {
       return null;
     }
     // Nowhere to look: no `public/` directory.
@@ -170,9 +183,9 @@ const checkPathLink = (
     return {
       ...site,
       code: "BLUME_BROKEN_ASSET",
-      message: `Asset ${resolved} was not found in the public directory.`,
+      message: `Asset ${assetPath} was not found in the public directory.`,
       severity: "warning",
-      suggestion: `Add the file at public${resolved} or fix the link.`,
+      suggestion: `Add the file at public${assetPath} or fix the link.`,
     };
   }
 
@@ -222,10 +235,11 @@ 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 ||
-    (!head.ok && head.status === undefined && !head.timedOut);
+    unreachable;
   return retry ? await request(url, "GET") : head;
 };
 
@@ -349,17 +363,23 @@ const classifyLink = (
 export const validateLinks = async (
   graph: ContentGraph,
   options: {
+    /** Site-wide route mount point (`""` or `/seg`); routes and redirects carry it. */
+    basePath?: string;
     publicDir: string | null;
     checkExternal?: boolean;
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: { from: string }[];
   }
 ): Promise<Diagnostic[]> => {
+  const basePath = options.basePath ?? "";
   const ctx: LinkContext = {
     anchors: buildAnchorIndex(graph.pages),
+    basePath,
     publicDir: options.publicDir,
     redirects: new Set(
-      (options.redirects ?? []).map((redirect) => toRoute(redirect.from))
+      (options.redirects ?? []).map((redirect) =>
+        toRoute(withBasePath(basePath, redirect.from))
+      )
     ),
     routes: new Set(graph.routes.keys()),
   };

package/src/core/manifest.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "./base-path.ts";
 import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import type {
@@ -26,6 +27,64 @@ export const contentIndexable = (
   !page.meta.search.exclude &&
   (!page.meta.sidebar.hidden || config.search.indexing.includeHiddenPages);
 
+/**
+ * Fallback materialization: render the fallback locale's content at the
+ * localized URL for any translation a non-default locale is missing, so static
+ * output is fully prerendered (render-fallback, no client redirect). Fallback
+ * routes are not indexed and carry no `hreflang` of their own.
+ */
+const buildFallbackRoutes = (
+  graph: ContentGraph,
+  i18n: NonNullable<ResolvedConfig["i18n"]>,
+  alternatesByKey: Map<string, RouteAlternate[]>,
+  basePath: string
+): RouteManifestEntry[] => {
+  const fallback = resolveFallbackLocale(i18n);
+  if (!fallback) {
+    return [];
+  }
+  const fallbackPages = new Map(
+    graph.pages.flatMap((page) =>
+      page.locale === fallback ? [[page.translationKey, page] as const] : []
+    )
+  );
+  const routes: RouteManifestEntry[] = [];
+  for (const { code } of i18n.locales) {
+    if (code === fallback) {
+      continue;
+    }
+    const present = new Set(
+      graph.pages.flatMap((page) =>
+        page.locale === code ? [page.translationKey] : []
+      )
+    );
+    for (const [key, source] of fallbackPages) {
+      if (present.has(key)) {
+        continue;
+      }
+      routes.push({
+        alternates: alternatesByKey.get(key) ?? [],
+        collection: source.collection ?? "docs",
+        contentType: source.contentType,
+        draft: source.meta.draft,
+        editUrl: source.editUrl,
+        entryId: source.entryId ?? source.source.ref,
+        fallback: true,
+        hidden: source.meta.sidebar.hidden,
+        id: source.id,
+        indexable: false,
+        lastModified: source.lastModified,
+        locale: code,
+        path: withBasePath(basePath, localizeRoute(key, code, i18n)),
+        source: source.source,
+        sourcePath: source.sourcePath,
+        title: source.title,
+      });
+    }
+  }
+  return routes;
+};
+
 /** Build the runtime manifest that bridges core and the generated Astro app. */
 export const buildManifest = (options: {
   context: ProjectContext;
@@ -65,52 +124,10 @@ export const buildManifest = (options: {
     title: page.title,
   }));
 
-  // Fallback materialization: render the fallback locale's content at the
-  // localized URL for any translation a non-default locale is missing, so static
-  // output is fully prerendered (render-fallback, no client redirect). Fallback
-  // routes are not indexed and carry no `hreflang` of their own.
   if (i18n) {
-    const fallback = resolveFallbackLocale(i18n);
-    if (fallback) {
-      const fallbackPages = new Map(
-        graph.pages
-          .filter((page) => page.locale === fallback)
-          .map((page) => [page.translationKey, page] as const)
-      );
-      for (const { code } of i18n.locales) {
-        if (code === fallback) {
-          continue;
-        }
-        const present = new Set(
-          graph.pages
-            .filter((page) => page.locale === code)
-            .map((page) => page.translationKey)
-        );
-        for (const [key, source] of fallbackPages) {
-          if (present.has(key)) {
-            continue;
-          }
-          routes.push({
-            alternates: alternatesByKey.get(key) ?? [],
-            collection: source.collection ?? "docs",
-            contentType: source.contentType,
-            draft: source.meta.draft,
-            editUrl: source.editUrl,
-            entryId: source.entryId ?? source.source.ref,
-            fallback: true,
-            hidden: source.meta.sidebar.hidden,
-            id: source.id,
-            indexable: false,
-            lastModified: source.lastModified,
-            locale: code,
-            path: localizeRoute(key, code, i18n),
-            source: source.source,
-            sourcePath: source.sourcePath,
-            title: source.title,
-          });
-        }
-      }
-    }
+    routes.push(
+      ...buildFallbackRoutes(graph, i18n, alternatesByKey, config.basePath)
+    );
   }
 
   routes.sort((a, b) => a.path.localeCompare(b.path));

package/src/core/nav-diagnostics.ts

@@ -157,7 +157,7 @@ const hiddenInSidebarDiagnostics = (
   pages: PageRecord[]
 ): Diagnostic[] => {
   const hidden = new Set(
-    pages.filter((page) => page.meta.sidebar.hidden).map((page) => page.id)
+    pages.flatMap((page) => (page.meta.sidebar.hidden ? [page.id] : []))
   );
   if (hidden.size === 0) {
     return [];

package/src/core/navigation.ts

@@ -1,5 +1,6 @@
 import { extname } from "pathe";
 
+import { stripBasePath, withBasePath } from "./base-path.ts";
 import type {
   FolderMeta,
   SidebarDisplay,
@@ -28,7 +29,7 @@ const humanize = (segment: string): string =>
 
 const numericOrder = (segment: string): number => {
   const value = segment.match(NUMERIC_PREFIX)?.groups?.order;
-  return value ? Number.parseInt(value, 10) : Number.POSITIVE_INFINITY;
+  return value ? Math.trunc(Number(value)) : Number.POSITIVE_INFINITY;
 };
 
 /** The nav key of a raw path segment: group label or numeric-stripped name. */
@@ -326,82 +327,100 @@ const normalizeRef = (ref: string): string => {
 
 const routeForRef = (
   ref: string | undefined,
-  byRoute: Map<string, PageRecord>
+  byRoute: Map<string, PageRecord>,
+  basePath: string
 ): string | undefined => {
   if (!ref) {
     return undefined;
   }
   const normalized = normalizeRef(ref);
-  return byRoute.get(normalized)?.route ?? normalized;
+  // A matched page carries an already-based `route`; an unmatched ref is an
+  // author-written root-relative path that still needs the base applied.
+  return byRoute.get(normalized)?.route ?? withBasePath(basePath, normalized);
+};
+
+/**
+ * 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
+ * by `buildConfigSidebar` itself so it owns the recursion.
+ */
+const configItemToNode = (
+  item: SidebarItemConfig,
+  byRoute: Map<string, PageRecord>,
+  basePath: string
+): NavNode | null => {
+  if (typeof item === "string") {
+    const page = byRoute.get(normalizeRef(item));
+    if (!page) {
+      return null;
+    }
+    return {
+      badge: page.meta.sidebar.badge,
+      deprecated: page.meta.deprecated || undefined,
+      description: page.description,
+      icon: page.meta.sidebar.icon,
+      kind: "page",
+      label: page.meta.sidebar.label ?? page.title,
+      pageId: page.id,
+      route: page.route,
+    };
+  }
+
+  if (item.root) {
+    const page = byRoute.get(normalizeRef(item.root));
+    return {
+      badge: item.badge,
+      deprecated: page?.meta.deprecated || undefined,
+      icon: item.icon,
+      kind: "page",
+      label: item.label,
+      pageId: page?.id ?? "",
+      route: page?.route ?? withBasePath(basePath, normalizeRef(item.root)),
+    };
+  }
+
+  if (item.href) {
+    return {
+      badge: item.badge,
+      icon: item.icon,
+      kind: "page",
+      label: item.label,
+      pageId: "",
+      route: withBasePath(basePath, item.href),
+    };
+  }
+
+  return null;
 };
 
 /** Build the sidebar tree from an explicit config spec. */
 const buildConfigSidebar = (
   items: SidebarItemConfig[],
   byRoute: Map<string, PageRecord>,
-  display: SidebarDisplay
+  display: SidebarDisplay,
+  basePath: string
 ): NavNode[] => {
   const nodes: NavNode[] = [];
-
   for (const item of items) {
-    if (typeof item === "string") {
-      const page = byRoute.get(normalizeRef(item));
-      if (page) {
-        nodes.push({
-          badge: page.meta.sidebar.badge,
-          deprecated: page.meta.deprecated || undefined,
-          description: page.description,
-          icon: page.meta.sidebar.icon,
-          kind: "page",
-          label: page.meta.sidebar.label ?? page.title,
-          pageId: page.id,
-          route: page.route,
-        });
-      }
-      continue;
-    }
-
-    if (item.items) {
+    if (typeof item !== "string" && item.items) {
       nodes.push({
         badge: item.badge,
-        children: buildConfigSidebar(item.items, byRoute, display),
+        children: buildConfigSidebar(item.items, byRoute, display, basePath),
         collapsed: item.collapsed,
         directory: item.directory,
         display: item.display ?? display,
         icon: item.icon,
         kind: "group",
         label: item.label,
-        route: routeForRef(item.root, byRoute),
+        route: routeForRef(item.root, byRoute, basePath),
       });
       continue;
     }
-
-    if (item.root) {
-      const page = byRoute.get(normalizeRef(item.root));
-      nodes.push({
-        badge: item.badge,
-        deprecated: page?.meta.deprecated || undefined,
-        icon: item.icon,
-        kind: "page",
-        label: item.label,
-        pageId: page?.id ?? "",
-        route: page?.route ?? normalizeRef(item.root),
-      });
-      continue;
-    }
-
-    if (item.href) {
-      nodes.push({
-        badge: item.badge,
-        icon: item.icon,
-        kind: "page",
-        label: item.label,
-        pageId: "",
-        route: item.href,
-      });
+    const node = configItemToNode(item, byRoute, basePath);
+    if (node) {
+      nodes.push(node);
     }
   }
-
   return nodes;
 };
 
@@ -409,6 +428,8 @@ const buildConfigSidebar = (
 export const buildNavigation = (
   pages: PageRecord[],
   options: {
+    /** Site-wide route mount point (`""` or `/seg`); applied to config paths. */
+    basePath?: string;
     folderMeta: Map<string, FolderMeta>;
     /** Global display mode for every sidebar group (default `flat`). */
     display?: SidebarDisplay;
@@ -428,24 +449,64 @@ export const buildNavigation = (
     sharedFolderMeta?: Map<string, FolderMeta>;
   }
 ): Navigation => {
-  const featured = options.featured ?? [];
-  const selectors = options.selectors ?? [];
-  const tabs = options.tabs ?? [];
+  const basePath = options.basePath ?? "";
   const display = options.display ?? "flat";
   const metaPrefix = options.metaPrefix ?? "";
   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,
+        items: tab.items?.map(rebasePath),
+        path: withBasePath(basePath, tab.path),
+      }))
+    : (options.tabs ?? []);
   const byRoute = new Map(
     pages.map((page) => [
       options.refByLogical ? page.translationKey : page.route,
       page,
     ])
   );
+  // Explicit-sidebar refs (`"foo/index"`) are authored as if mounted at root,
+  // but `page.route` carries the base — alias each page under its base-less
+  // route so a bare ref still resolves. (The i18n `refByLogical` map is already
+  // keyed by the base-less `translationKey`, so it needs no alias.)
+  if (basePath && !options.refByLogical) {
+    for (const page of pages) {
+      const bare = stripBasePath(basePath, page.route);
+      if (!byRoute.has(bare)) {
+        byRoute.set(bare, page);
+      }
+    }
+  }
 
   if (options.sidebar) {
     return {
       featured,
       selectors,
-      sidebar: buildConfigSidebar(options.sidebar, byRoute, display),
+      sidebar: buildConfigSidebar(options.sidebar, byRoute, display, basePath),
       tabs,
     };
   }
@@ -459,7 +520,7 @@ export const buildNavigation = (
       sharedFolderMeta,
       metaPrefix,
       display,
-      new Set(tabs.map((tab) => tab.path).filter((path) => path !== "/"))
+      new Set(tabs.flatMap((tab) => (tab.path === "/" ? [] : [tab.path])))
     ),
     tabs,
   };

package/src/core/project-graph.ts

@@ -158,12 +158,11 @@ export const scanProject = async (
   // Folder meta is discovered per filesystem source, under each source's own
   // root and keyed by its route prefix, so a prefixed/root-differing source's
   // `meta.ts` still lines up with its (prefixed) sidebar group path.
-  const metaSources: FolderMetaSource[] = sources
-    .filter((source) => !source.staged && source.contentRoot)
-    .map((source) => ({
-      prefix: source.prefix,
-      root: source.contentRoot ?? "",
-    }));
+  const metaSources: FolderMetaSource[] = sources.flatMap((source) =>
+    source.staged || !source.contentRoot
+      ? []
+      : [{ prefix: source.prefix, root: source.contentRoot }]
+  );
 
   // Run every source's `load()` in parallel, then funnel each entry through the
   // shared `normalizeEntry` so route mapping is identical regardless of origin.
@@ -172,9 +171,9 @@ export const scanProject = async (
   // `discoverFolderMeta`).
   const localeDirs =
     config.i18n && config.i18n.parser === "dir"
-      ? config.i18n.locales
-          .map((locale) => locale.code)
-          .filter((code) => code !== config.i18n?.defaultLocale)
+      ? config.i18n.locales.flatMap((locale) =>
+          locale.code === config.i18n?.defaultLocale ? [] : [locale.code]
+        )
       : undefined;
 
   const [loaded, folderMeta] = await Promise.all([
@@ -190,6 +189,7 @@ export const scanProject = async (
     contentDiagnostics.push(...diagnostics);
     for (const entry of entries) {
       const normalized = normalizeEntry(entry, {
+        basePath: config.basePath,
         defaultType: config.content.defaultType,
         i18n: config.i18n,
         source: {
@@ -230,6 +230,7 @@ export const scanProject = async (
   }
 
   const graph = buildContentGraph(pages, {
+    basePath: config.basePath,
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,