blume 2.0.1 → 2.0.2

package/src/core/links.ts

@@ -109,10 +109,11 @@ const NUMERIC_PREFIX = /^\d+[-_.]/u;
  * falsely flagged as broken. Tested against `navPath` — the locale-stripped
  * path — so a dot-parser localized index (`index.fr.mdx`) and a shared
  * locale-agnostic one (`index.$.mdx`) count too, matching how route mapping
- * recognizes them.
+ * recognizes them. Only a lowercase `index` counts, as in route mapping:
+ * `Index.md` publishes at `…/Index`, a page of its own.
  */
 const isIndexPage = (page: PageRecord): boolean =>
-  /^index\.(?:md|mdx)$/iu.test(
+  /^index\.[Mm][Dd][Xx]?$/u.test(
     basename(page.navPath).replace(NUMERIC_PREFIX, "")
   );
 
@@ -218,14 +219,16 @@ export const resolveRelativeHref = (
  * Whether a content file is its folder's index, from its name as written on
  * disk: `index.md(x)` after an ordering prefix, optionally carrying one of
  * `localeTokens` before the extension (`index.fr.mdx` under the `dot` locale
- * parser, `index.$.mdx` for a file shared by every locale).
+ * parser, `index.$.mdx` for a file shared by every locale). The `index` itself
+ * is case-sensitive, as route mapping reads it: `Index.md` is a page named
+ * `Index`, not its folder's index.
  */
 export const isIndexFileName = (
   name: string,
   localeTokens: readonly string[] = []
 ): boolean => {
   const stem = basename(name).replace(NUMERIC_PREFIX, "");
-  const match = /^index(?:\.(?<token>[^./]+))?\.(?:md|mdx)$/iu.exec(stem);
+  const match = /^index(?:\.(?<token>[^./]+))?\.[Mm][Dd][Xx]?$/u.exec(stem);
   if (!match) {
     return false;
   }

package/src/core/load-module.ts

@@ -14,3 +14,23 @@ export const createModuleLoader = (): ((file: string) => Promise<unknown>) => {
     return loaded?.default ?? loaded;
   };
 };
+
+/**
+ * Create a loader for a module whose default export is its whole value
+ * (`blume.config.ts`). Unlike {@link createModuleLoader}, it never falls back
+ * to the module's namespace: a module with no default export, or one that
+ * exports `null`/`undefined`, resolves to `undefined` so the caller can say
+ * so, instead of validating `{}` (a bare `defineConfig({…})` call) or
+ * `{ config }` (a named export). jiti's default interop is off because it
+ * throws on `export default null`.
+ */
+export const createDefaultExportLoader: typeof createModuleLoader = () => {
+  const jiti = createJiti(import.meta.url, {
+    interopDefault: false,
+    moduleCache: false,
+  });
+  return async (file: string) => {
+    const loaded = await jiti.import<{ default?: unknown }>(file);
+    return loaded.default ?? undefined;
+  };
+};

package/src/core/locale-links.ts

@@ -44,13 +44,6 @@ export interface LocalizeLinkOptions {
   routes: RouteSet;
 }
 
-/**
- * Mirrors the asset heuristic in `markdown/base-links.ts`: a path whose final
- * segment carries a file extension is a `public/` asset (or a raw `.md` twin),
- * served at the site root and never localized.
- */
-const ASSET_PATH = /\.[a-z0-9]+$/iu;
-
 /** Decode a percent-encoded path for a route lookup; leave junk as-is. */
 const decodePercent = (value: string): string => {
   try {
@@ -60,6 +53,13 @@ const decodePercent = (value: string): string => {
   }
 };
 
+/**
+ * Whether `routes` serves `route` (base-prefixed, fragment-less). Routes are
+ * stored decoded, so a browser-copied `/caf%C3%A9` still finds its page.
+ */
+export const servesRoute = (routes: RouteSet, route: string): boolean =>
+  routes.has(route) || routes.has(decodePercent(route));
+
 /** Whether `path` (base-stripped) already sits under some locale's prefix. */
 const hasLocalePrefix = (path: string, i18n: LocaleRouting): boolean =>
   i18n.locales.some((locale) => {
@@ -85,11 +85,9 @@ export const localizeLinkPath = (
     return path;
   }
   const localized = withBasePath(basePath, localizeRoute(rest, locale, i18n));
-  // Routes are stored decoded; a browser-copied `/caf%C3%A9` must still find
-  // its translation, but the emitted href keeps the author's encoding.
-  return routes.has(localized) || routes.has(decodePercent(localized))
-    ? localized
-    : path;
+  // A browser-copied `/caf%C3%A9` must still find its translation, but the
+  // emitted href keeps the author's encoding.
+  return servesRoute(routes, localized) ? localized : path;
 };
 
 export interface LocalizeHrefOptions extends LocalizeLinkOptions {
@@ -98,9 +96,14 @@ export interface LocalizeHrefOptions extends LocalizeLinkOptions {
 }
 
 /**
- * Localize a rendered `href`: external URLs, relative paths, bare fragments, and
- * asset links pass through; a root-relative page link keeps its `?query` and
+ * Localize a rendered `href`: external URLs, relative paths, and bare
+ * fragments pass through; a root-relative page link keeps its `?query` and
  * `#fragment` and its `deployment.base` layer around the localized path.
+ *
+ * Asset links (`/logo.png`, a raw `.md` twin) pass through too, because no
+ * page is served at their localized path — the same served-route test the
+ * link checker applies. A file extension alone doesn't mark an asset: a
+ * dotted page route (`/releases/v1.2`) is localized like any other page.
  */
 export const localizeHref = (
   href: string,
@@ -112,9 +115,6 @@ export const localizeHref = (
   const suffixAt = href.search(/[#?]/u);
   const path = suffixAt === -1 ? href : href.slice(0, suffixAt);
   const suffix = suffixAt === -1 ? "" : href.slice(suffixAt);
-  if (ASSET_PATH.test(path)) {
-    return href;
-  }
   const based = stripBasePath(options.deployBase, path);
   const localized = localizeLinkPath(based, options);
   if (localized === based) {

package/src/core/manifest.ts

@@ -1,4 +1,4 @@
-import { withBasePath } from "./base-path.ts";
+import { mountBasePath } from "./base-path.ts";
 import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
 import type { ResolvedConfig } from "./schema.ts";
 import type {
@@ -106,7 +106,7 @@ const buildFallbackRoutes = (
       if (present.has(key)) {
         continue;
       }
-      const path = withBasePath(basePath, localizeRoute(key, code, i18n));
+      const path = mountBasePath(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
@@ -183,6 +183,7 @@ export const buildManifest = (options: {
   }
 
   const routes: RouteManifestEntry[] = graph.pages.map((page) => ({
+    aiExclude: page.meta.ai.exclude,
     alternates: alternatesByKey.get(page.translationKey) ?? [],
     collection: page.collection ?? "docs",
     contentType: page.contentType,

package/src/core/meta.ts

@@ -1,5 +1,5 @@
 import { basename, dirname, relative } from "pathe";
-import { glob } from "tinyglobby";
+import { glob, isDynamicPattern } from "tinyglobby";
 
 import { diagnosticsFromZod } from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
@@ -38,12 +38,57 @@ const resolveMeta = async (mod: MetaModuleExport) =>
 
 /** 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
- * with the sidebar group path, which carries the same prefix. */
+ * with the sidebar group path, which carries the same prefix. `include` and
+ * `exclude` are the source's content globs, which scope the scan to the
+ * folders the source reads. */
 export interface FolderMetaSource {
   root: string;
   prefix?: string;
+  include?: readonly string[];
+  exclude?: readonly string[];
 }
 
+/**
+ * The literal directory a glob starts from (`docs/**\/*.md` → `docs`, `""`
+ * when it matches from the root): its leading segments up to the first one
+ * with glob syntax, the file-name segment excluded.
+ */
+const globBase = (pattern: string): string => {
+  const literal: string[] = [];
+  for (const segment of pattern.split("/").slice(0, -1)) {
+    if (isDynamicPattern(segment)) {
+      break;
+    }
+    if (segment !== "" && segment !== ".") {
+      literal.push(segment);
+    }
+  }
+  return literal.join("/");
+};
+
+/** Whether `dir` is `base`, or nested beneath or above it (`""` is the root). */
+const onPathOf = (dir: string, base: string): boolean =>
+  dir === base ||
+  base === "" ||
+  dir === "" ||
+  dir.startsWith(`${base}/`) ||
+  base.startsWith(`${dir}/`);
+
+/**
+ * Whether a meta file's directory can configure a sidebar group of the
+ * source: it lies on the path of some `include` glob's base — the folders
+ * that glob reads, or the ancestors whose groups hold them. Negated globs
+ * only narrow what a source reads, so they never qualify a folder.
+ */
+const withinInclude = (
+  dir: string,
+  include: readonly string[] | undefined
+): boolean =>
+  include === undefined ||
+  include.some(
+    (pattern) => !pattern.startsWith("!") && onPathOf(dir, globBase(pattern))
+  );
+
 /**
  * The folder-meta key for a directory. Mirrors the sidebar group path: the
  * source's route prefix (`docs`) followed by the directory relative to the
@@ -93,7 +138,12 @@ export const discoverFolderMeta = async (
   const list: FolderMetaSource[] = Array.isArray(sources)
     ? sources
     : [{ root: sources }];
-  const localeDirs = new Set(options.localeDirs);
+  // Locale folders match case-insensitively, like content does (`pt-br/` for
+  // a configured `pt-BR`), and key under the configured casing, which is what
+  // navigation looks meta up by.
+  const localeDirs = new Map(
+    (options.localeDirs ?? []).map((code) => [code.toLowerCase(), code])
+  );
   const versionDirs = new Set(options.versionDirs);
 
   const load = createModuleLoader();
@@ -105,14 +155,25 @@ export const discoverFolderMeta = async (
   // `content.root` still contributes its folder meta.
   const perSource = await Promise.all(
     list.map(async (source) => {
-      const files = await glob(META_FILES, {
+      const found = await glob(META_FILES, {
         absolute: true,
         cwd: source.root,
         // Never descend into dependencies or build output — relevant when the
         // root is the project root (e.g. a `.`-rooted or all-staged project).
-        ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
+        // The source's own `exclude` applies too: a `meta.ts` under an
+        // excluded folder (`src/lib/meta.ts` beside `exclude: ["src/**"]`)
+        // is application code, not folder meta, and importing it would fail.
+        ignore: [
+          ...(source.exclude ?? []),
+          "**/node_modules/**",
+          "**/.blume/**",
+          "**/dist/**",
+        ],
         onlyFiles: true,
       });
+      const files = found.filter((file) =>
+        withinInclude(relative(source.root, dirname(file)), source.include)
+      );
       const loaded = await Promise.all(
         files.map(
           async (
@@ -149,7 +210,9 @@ export const discoverFolderMeta = async (
       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 locale = localeHead
+        ? (localeDirs.get(localeHead.toLowerCase()) ?? "")
+        : "";
       const rest = (locale ? localeTail : afterVersion)
         .filter(Boolean)
         .join("/");

package/src/core/nav-diagnostics.ts

@@ -1,6 +1,8 @@
 import { isAssetIcon } from "../theme/icon-kind.ts";
 import { hasIcon } from "../theme/icons.ts";
 import { isInternalPath } from "./base-path.ts";
+import { isPageRef, normalizeRef } from "./navigation.ts";
+import type { SidebarItemConfig } from "./schema.ts";
 import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
 
 /**
@@ -137,7 +139,9 @@ export const validateNavTargets = (
     if (!isInternalPath(path) || path.startsWith("/#") || seen.has(path)) {
       continue;
     }
-    if (!resolvesToPages(routes, path.split("#")[0] ?? path)) {
+    // A query or fragment (`/guides?tab=cli`) rides on the route; only the
+    // path names a page.
+    if (!resolvesToPages(routes, path.split(/[?#]/u)[0] ?? path)) {
       seen.add(path);
       diagnostics.push({
         code: "BLUME_NAV_MISSING_PAGE",
@@ -150,6 +154,57 @@ export const validateNavTargets = (
   return diagnostics;
 };
 
+/**
+ * Warn about explicit `navigation.sidebar` items that can't render as written,
+ * instead of dropping them without a word: a page ref that matches no page
+ * (left out of the sidebar), a `root` that matches no page (its link leads
+ * nowhere), and an item with no page, `href`, `root`, or `items` (left out).
+ * `resolves` answers whether a normalized ref (`/guides`) names a page — in
+ * any locale — or a route served outside the content tree.
+ */
+export const validateSidebarItems = (
+  items: SidebarItemConfig[],
+  resolves: (route: string) => boolean
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const walk = (list: SidebarItemConfig[]): void => {
+    for (const item of list) {
+      if (isPageRef(item)) {
+        if (!resolves(normalizeRef(item))) {
+          diagnostics.push({
+            code: "BLUME_NAV_MISSING_PAGE",
+            message: `Sidebar entry "${item}" matches no page, so it's left out of the sidebar.`,
+            severity: "warning",
+            suggestion: "Fix the route, or add a page at it.",
+          });
+        }
+        continue;
+      }
+      if (item.root && !resolves(normalizeRef(item.root))) {
+        diagnostics.push({
+          code: "BLUME_NAV_MISSING_PAGE",
+          message: `Sidebar entry "${item.label}" has root "${item.root}", but no page matches it, so its link leads nowhere.`,
+          severity: "warning",
+          suggestion: "Fix the root, or add a page at that route.",
+        });
+      }
+      if (item.items) {
+        walk(item.items);
+      } else if (!(item.root || item.href)) {
+        diagnostics.push({
+          code: "BLUME_NAV_EMPTY_ITEM",
+          message: `Sidebar entry "${item.label}" has no page, href, root, or items, so it's left out of the sidebar.`,
+          severity: "warning",
+          suggestion:
+            "Give it an href or a root to link somewhere, or items to make it a group.",
+        });
+      }
+    }
+  };
+  walk(items);
+  return diagnostics;
+};
+
 /** Warn about two nav items sharing a label at the same sidebar level. */
 const duplicateLabelDiagnostics = (navigation: Navigation): Diagnostic[] => {
   const diagnostics: Diagnostic[] = [];