blume 1.4.2 → 1.5.0

package/src/core/sources/portable-text.ts

@@ -5,6 +5,23 @@
  * Markdown text that flows through Blume's normal pipeline.
  */
 
+/**
+ * A field value on a Portable Text node: the arbitrary JSON the CMS query
+ * returned (custom blocks carry whatever fields the studio schema defines).
+ * Spans and mark defs appear as members so the block's typed fields conform
+ * to its index signature.
+ */
+export type PortableTextValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | PortableTextSpan
+  | PortableTextMarkDef
+  | PortableTextValue[]
+  | { [key: string]: PortableTextValue };
+
 /** A single Portable Text node (block, image, or a custom type). */
 export interface PortableTextBlock {
   _type: string;
@@ -14,7 +31,7 @@ export interface PortableTextBlock {
   level?: number;
   children?: PortableTextSpan[];
   markDefs?: PortableTextMarkDef[];
-  [key: string]: unknown;
+  [key: string]: PortableTextValue;
 }
 
 interface PortableTextSpan {
@@ -36,21 +53,36 @@ export interface PortableTextOptions {
   serializers?: Record<string, (block: PortableTextBlock) => string>;
 }
 
-const HEADING_STYLES: Record<string, string> = {
-  h1: "# ",
-  h2: "## ",
-  h3: "### ",
-  h4: "#### ",
-  h5: "##### ",
-  h6: "###### ",
-};
+const HEADING_STYLES = new Map([
+  ["h1", "# "],
+  ["h2", "## "],
+  ["h3", "### "],
+  ["h4", "#### "],
+  ["h5", "##### "],
+  ["h6", "###### "],
+]);
+
+// Markdown/raw-HTML structure characters. Portable Text spans are *plain
+// text* — formatting arrives as marks, never as syntax in the text — so a
+// literal `*`, `_`, `[`, backtick, `~`, or `<` typed in the CMS must render
+// as itself. Unescaped, it opened emphasis or a code span mid-paragraph, and
+// `<` let CMS prose inject raw HTML into the rendered page. CommonMark
+// backslash-escapes every ASCII punctuation character, so `\*` is always the
+// literal asterisk.
+const MARKDOWN_SPECIALS = /[\\`*_[\]~<]/gu;
+
+const escapeText = (text: string): string =>
+  text.replaceAll(MARKDOWN_SPECIALS, String.raw`\$&`);
 
 /** Wrap a span's text in Markdown for its marks (decorators + link defs). */
 const renderSpan = (
   span: PortableTextSpan,
   defs: Map<string, PortableTextMarkDef>
 ): string => {
-  let text = span.text ?? "";
+  // Code spans stay verbatim: their text is literal inside the backticks,
+  // and backslash escapes would render as backslashes.
+  const isCode = span.marks?.includes("code") ?? false;
+  let text = isCode ? (span.text ?? "") : escapeText(span.text ?? "");
   if (!span.marks || span.marks.length === 0) {
     return text;
   }
@@ -93,6 +125,10 @@ const renderChildren = (block: PortableTextBlock): string => {
   return (block.children ?? []).map((span) => renderSpan(span, defs)).join("");
 };
 
+/** Whether an image block's `alt` field is usable alt text (CMS JSON may hold anything). */
+const isAltText = (value: PortableTextValue): value is string =>
+  typeof value === "string";
+
 const renderBlock = (
   block: PortableTextBlock,
   options: PortableTextOptions
@@ -103,7 +139,7 @@ const renderBlock = (
   }
   if (block._type === "image") {
     const url = options.imageUrl?.(block);
-    const alt = typeof block.alt === "string" ? block.alt : "";
+    const alt = isAltText(block.alt) ? block.alt : "";
     return url ? `![${alt}](${url})` : "";
   }
   if (block._type !== "block") {
@@ -119,7 +155,7 @@ const renderBlock = (
   if (block.style === "blockquote") {
     return `> ${inline}`;
   }
-  return `${HEADING_STYLES[block.style ?? "normal"] ?? ""}${inline}`;
+  return `${HEADING_STYLES.get(block.style ?? "normal") ?? ""}${inline}`;
 };
 
 /** Serialize a Portable Text array into a Markdown string. */

package/src/core/sources/resolve.ts

@@ -86,6 +86,7 @@ const buildSource = (
   if (def.type === "notion") {
     return notionSource(
       {
+        concurrency: def.concurrency,
         database: def.database,
         name,
         pollInterval: def.pollInterval,

package/src/core/sources/sanity.ts

@@ -59,12 +59,44 @@ export interface SanitySourceOptions {
 
 const IMAGE_REF = /^image-(?<id>[a-f0-9]+)-(?<dims>\d+x\d+)-(?<ext>\w+)$/u;
 
+/** A value in a fetched document: arbitrary JSON the GROQ query returned. */
+type SanityValue =
+  | string
+  | number
+  | boolean
+  | null
+  | SanityValue[]
+  | { [key: string]: SanityValue };
+
+/** A document as the GROQ query returns it. */
+interface SanityDocument {
+  [key: string]: SanityValue;
+}
+
+/** The frontmatter fields this adapter maps from a document. */
+interface SanityFrontmatter {
+  description?: string;
+  title?: string;
+}
+
+/**
+ * A node a dot path can descend into. Arrays pass too (matching their runtime
+ * string-key indexing, e.g. `items.0`), so the predicate types them as the
+ * keyed form both traverse through.
+ */
+const isTraversable = (
+  value: SanityValue | undefined
+): value is SanityDocument => typeof value === "object" && value !== null;
+
 /** Resolve a dot path (`slug.current`) against a document. */
-const getPath = (doc: Record<string, unknown>, path: string): unknown => {
-  let current: unknown = doc;
+const getPath = (
+  doc: SanityDocument,
+  path: string
+): SanityValue | undefined => {
+  let current: SanityValue | undefined = doc;
   for (const key of path.split(".")) {
-    if (current && typeof current === "object") {
-      current = (current as Record<string, unknown>)[key];
+    if (isTraversable(current)) {
+      current = current[key];
     } else {
       return;
     }
@@ -72,8 +104,11 @@ const getPath = (doc: Record<string, unknown>, path: string): unknown => {
   return current;
 };
 
-const asString = (value: unknown): string | undefined =>
-  typeof value === "string" ? value : undefined;
+const isStringValue = (value: SanityValue | undefined): value is string =>
+  typeof value === "string";
+
+const asString = (value: SanityValue | undefined): string | undefined =>
+  isStringValue(value) ? value : undefined;
 
 /** Build a Sanity CDN URL from an image asset `_ref`. */
 const imageUrlFromRef = (
@@ -89,6 +124,16 @@ const imageUrlFromRef = (
   return `https://cdn.sanity.io/images/${projectId}/${dataset}/${id}-${dims}.${ext}`;
 };
 
+/** The `createClient` config slice this adapter passes. */
+interface SanityClientConfig {
+  apiVersion: string;
+  dataset: string;
+  perspective: "previewDrafts" | "published";
+  projectId: string;
+  token: string | undefined;
+  useCdn: boolean;
+}
+
 const resolveClient = async (
   options: SanitySourceOptions,
   preview: boolean
@@ -96,10 +141,13 @@ const resolveClient = async (
   if (options.client) {
     return options.client;
   }
-  let createClient: (config: Record<string, unknown>) => SanityClientLike;
+  let createClient: (config: SanityClientConfig) => SanityClientLike;
   try {
+    // SAFETY: `@sanity/client` is an optional dependency; its `createClient`
+    // accepts a superset of this config slice and returns a client exposing
+    // the `fetch` method this adapter uses.
     ({ createClient } = (await import("@sanity/client")) as {
-      createClient: (config: Record<string, unknown>) => SanityClientLike;
+      createClient: (config: SanityClientConfig) => SanityClientLike;
     });
   } catch {
     throw new BlumeError({
@@ -135,7 +183,7 @@ export const sanitySource = (
   );
   let snapshot = new Map<string, SourceEntry>();
 
-  const toEntry = (doc: Record<string, unknown>): SourceEntry => {
+  const toEntry = (doc: SanityDocument): SourceEntry => {
     const slugValue =
       asString(getPath(doc, fields.slug ?? "slug.current")) ??
       asString(doc._id) ??
@@ -148,7 +196,7 @@ export const sanitySource = (
     const slug =
       slugifyPath(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
 
-    const data: Record<string, unknown> = {};
+    const data: SanityFrontmatter = {};
     const title = asString(getPath(doc, fields.title ?? "title"));
     const description = asString(
       getPath(doc, fields.description ?? "description")
@@ -160,11 +208,17 @@ export const sanitySource = (
       data.description = description;
     }
 
+    // SAFETY: the configured body field holds Portable Text blocks; a value of
+    // any other shape fails the `Array.isArray` check below and yields an
+    // empty body, and the serializer tolerates malformed blocks.
     const blocks = (getPath(doc, fields.body ?? "body") ??
       []) as PortableTextBlock[];
     const markdown = Array.isArray(blocks)
       ? portableTextToMarkdown(blocks, {
           imageUrl: (block) => {
+            // SAFETY: `asset` on an image block is Sanity's asset reference
+            // object; any other shape yields no `_ref` and the image is
+            // skipped.
             const ref = (block.asset as { _ref?: string } | undefined)?._ref;
             return ref
               ? imageUrlFromRef(ref, options.projectId, options.dataset)
@@ -177,7 +231,9 @@ export const sanitySource = (
     const raw = matter.stringify(markdown, data);
     return {
       body: { format: "md", text: markdown },
-      data,
+      // Spread into a fresh literal: `SourceEntry.data` wants an
+      // index-signature type, which the named interface lacks.
+      data: { ...data },
       hash: hashText(raw),
       lastModified: asString(getPath(doc, fields.lastModified ?? "_updatedAt")),
       raw,
@@ -193,9 +249,7 @@ export const sanitySource = (
       cache,
       async () => {
         const client = await resolveClient(options, ctx?.preview ?? false);
-        const docs = await client.fetch<Record<string, unknown>[]>(
-          options.query
-        );
+        const docs = await client.fetch<SanityDocument[]>(options.query);
         return docs.map(toEntry);
       },
       refresh

package/src/core/sources/types.ts

@@ -1,4 +1,9 @@
-import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
+import type {
+  FolderMeta,
+  FrontmatterExtend,
+  ResolvedI18nConfig,
+  ResolvedVersionsConfig,
+} from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 
 /**
@@ -12,6 +17,7 @@ export interface SourceEntry {
   /** Logical route input; defaults to `ref` if omitted. May include slashes. */
   slug?: string;
   /** Frontmatter-equivalent metadata, validated against the Blume meta schema. */
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- pre-validation frontmatter from YAML/CMS payloads; the meta schema parses it downstream
   data: Record<string, unknown>;
   /** The renderable body as Markdown/MDX source text (frontmatter stripped). */
   body: { format: "md" | "mdx"; text: string };
@@ -40,6 +46,14 @@ export interface SourceLoadResult {
   entries: SourceEntry[];
   /** Source-level diagnostics (e.g. an offline cache fallback warning). */
   diagnostics: Diagnostic[];
+  /**
+   * Folder meta the source derives for the sidebar groups its entries create,
+   * keyed by locale-stripped group path (the `meta.ts` key space). The OpenAPI
+   * source labels each tag directory with the spec's own tag name, so the
+   * sidebar shows `OAuth2`/`Größe` instead of a re-humanized slug. Merged
+   * beneath user-authored meta files, which always win.
+   */
+  folderMeta?: Record<string, FolderMeta>;
 }
 
 /**
@@ -117,4 +131,6 @@ export interface NormalizeContext {
    * applied to a page only when its resolved `type` matches.
    */
   typeFrontmatter?: Record<string, FrontmatterExtend>;
+  /** Docs versioning config; a leading archived-version dir becomes the page's version. */
+  versions?: ResolvedVersionsConfig;
 }

package/src/core/sources/watch.ts

@@ -71,7 +71,7 @@ export const ignoringWatchListener = (
   const ignore = new Set(ignoreDirs);
   return (_event, filename) => {
     if (
-      typeof filename === "string" &&
+      filename !== null &&
       filename.split(/[/\\]/u).some((segment) => ignore.has(segment))
     ) {
       return;

package/src/core/standard-schema.ts

@@ -38,7 +38,7 @@ export interface StandardSchema<Input = unknown, Output = Input> {
     readonly version: 1;
     readonly vendor: string;
     readonly validate: (
-      value: unknown
+      value: Input
     ) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
     readonly types?:
       | { readonly input: Input; readonly output: Output }
@@ -46,9 +46,15 @@ export interface StandardSchema<Input = unknown, Output = Input> {
   };
 }
 
-/** Whether a config-supplied value implements the `~standard` contract. */
-export const isStandardSchema = (value: unknown): value is StandardSchema =>
+/**
+ * Whether a config-supplied value implements the `~standard` contract. Generic
+ * so it can decode any input at the config boundary (`z.custom` hands it the
+ * raw config value) while narrowing whatever type the caller holds.
+ */
+export const isStandardSchema = <T>(value: T): value is T & StandardSchema =>
   typeof value === "object" &&
   value !== null &&
+  // SAFETY: the assertion only widens the checked object for property probing;
+  // the trailing typeof check is what verifies `~standard.validate` exists.
   typeof (value as { "~standard"?: { validate?: unknown } })["~standard"]
     ?.validate === "function";

package/src/core/text-width.ts

@@ -0,0 +1,26 @@
+import stringWidth from "string-width";
+
+/**
+ * The longest prefix of `text` that renders within `max` display columns
+ * without cutting inside a grapheme cluster. Columns are `string-width`'s: a
+ * fullwidth or wide character counts 2, a combining mark 0, everything else 1
+ * — the same measure `blume audit` grades titles and meta descriptions with,
+ * so text cut here stays inside the audit's thresholds for every script, not
+ * just Latin. Grapheme segmentation is rule-based (UAX #29), so unlike word
+ * segmentation it does not drift across ICU builds, and it can never split a
+ * surrogate pair or halve an emoji sequence.
+ */
+export const columnsPrefix = (text: string, max: number): string => {
+  let end = 0;
+  let used = 0;
+  const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+  for (const { index, segment } of graphemes.segment(text)) {
+    const width = stringWidth(segment);
+    if (used + width > max) {
+      break;
+    }
+    used += width;
+    end = index + segment.length;
+  }
+  return text.slice(0, end);
+};

package/src/core/tsconfig-aliases.ts

@@ -30,16 +30,20 @@ const substituteConfigDir = (value: string, configDir: string): string =>
     ? join(configDir, value.slice(CONFIG_DIR_TEMPLATE.length))
     : value;
 
+/** Whether a `paths` fallback entry is a usable target (raw JSONC may lie). */
+const isPathTarget = (target: string | undefined): target is string =>
+  typeof target === "string";
+
 /** Convert one tsconfig `paths` mapping to a Vite alias, or null to skip. */
 const toAlias = (
   key: string,
-  value: unknown,
+  value: string | string[],
   baseDir: string,
   configDir: string
 ): { find: string; replacement: string } | null => {
   // tsconfig allows a fallback array; Vite aliases are 1:1, so take the first.
   const first = Array.isArray(value) ? value[0] : value;
-  if (typeof first !== "string") {
+  if (!isPathTarget(first)) {
     return null;
   }
   const find = key.endsWith("/*") ? key.slice(0, -2) : key;
@@ -86,12 +90,12 @@ export const resolveTsconfigAliases = (
     configDir,
     substituteConfigDir(options?.baseUrl ?? ".", configDir)
   );
-  const aliases: Record<string, string> = {};
+  const entries: [string, string][] = [];
   for (const [key, value] of Object.entries(paths)) {
     const alias = toAlias(key, value, baseDir, configDir);
     if (alias) {
-      aliases[alias.find] = alias.replacement;
+      entries.push([alias.find, alias.replacement]);
     }
   }
-  return aliases;
+  return Object.fromEntries(entries);
 };

package/src/core/types.ts

@@ -121,9 +121,24 @@ export interface PageRecord {
   locale: string;
   /**
    * Locale-agnostic logical route shared by every translation (e.g.
-   * `/guides/x`). Pages with the same key are translations of each other.
+   * `/guides/x`, or `/v1.0/guides/x` under versioning — the key is
+   * version-specific, so translations group within their version).
+   * Pages with the same key are translations of each other.
    */
   translationKey: string;
+  /**
+   * Resolved docs version: an archived id (`v1.0`) for snapshot pages, `""`
+   * for the current (unprefixed) docs — including every page of an
+   * unversioned project.
+   */
+  version: string;
+  /**
+   * Version- and locale-agnostic logical route (e.g. `/guides/x` for
+   * `/v1.0/guides/x`). Pages with the same key and locale are the same
+   * logical page across versions — this drives the switcher's same-page
+   * navigation and the canonical-to-latest lookup.
+   */
+  versionKey: string;
   /**
    * True for entries filled in from the fallback locale to pad a locale's
    * navigation for pages it hasn't translated yet. The record's content —
@@ -151,6 +166,7 @@ export interface PageRecord {
    * schemas (schema output, so transforms apply). Present only when the
    * project opts in and the page carries at least one value.
    */
+  // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- values are outputs of arbitrary user-supplied zod schemas (transforms included), so no narrower type exists
   custom?: Record<string, unknown>;
   headings: Heading[];
   /** Whether the file is `.md`/`.mdx`. */
@@ -180,7 +196,12 @@ export type NavNode =
       label: string;
       badge?: string;
       directory?: DirectoryMode;
-      display?: SidebarDisplay;
+      /**
+       * The group's resolved render mode. Always stamped by both builders
+       * (generated and explicit-config sidebars), so the renderer can rely
+       * on it per node.
+       */
+      display: SidebarDisplay;
       icon?: string;
       route?: string;
       /**
@@ -266,6 +287,12 @@ export interface ContentGraph {
   navigation: Navigation;
   /** Navigation per locale; one entry per configured locale under i18n. */
   navigationByLocale: Record<string, Navigation>;
+  /**
+   * Navigation per archived version, keyed by version id and then locale code
+   * (`""` on a single-locale site). The current version's trees are
+   * `navigation`/`navigationByLocale`; empty when versioning is off.
+   */
+  navigationByVersion: Record<string, Record<string, Navigation>>;
   /** Map of route -> pageId for fast lookup and duplicate detection. */
   routes: Map<string, string>;
   diagnostics: Diagnostic[];
@@ -289,6 +316,13 @@ export interface LocaleSwitchOption {
   untranslated: boolean;
 }
 
+/** A docs version a logical page exists in, for the switcher and canonicals. */
+export interface VersionAlternate {
+  /** Version id; `""` for the current (unprefixed) docs. */
+  version: string;
+  path: string;
+}
+
 /** A route entry written to `blume.manifest.json`. */
 export interface RouteManifestEntry {
   id: string;
@@ -313,6 +347,15 @@ export interface RouteManifestEntry {
   locale: string;
   /** Locales this logical page is genuinely translated into (excludes fallbacks). */
   alternates: RouteAlternate[];
+  /** Resolved docs version (`""` for the current docs; see `PageRecord.version`). */
+  version: string;
+  /**
+   * Versions this logical page exists in within this route's locale — the
+   * current version first, then archived versions in configured order. Drives
+   * the switcher's same-page navigation and the canonical-to-latest lookup.
+   * Empty when versioning is off.
+   */
+  versionAlternates: VersionAlternate[];
   /** True when this route renders fallback content for a missing translation. */
   fallback?: boolean;
   /** Resolved "last updated" ISO date, when the feature is enabled. */

package/src/core/ui-packs/index.ts

@@ -47,7 +47,15 @@ import { zh } from "./zh.ts";
  * `zh-TW`). A locale's pack is merged onto English by {@link resolveUIStrings},
  * so a pack only needs the keys it translates.
  */
-export const UI_PACKS: Record<string, UIStringsOverride> = {
+/**
+ * Starter packs keyed by locale code. Open-keyed on purpose: resolvers look
+ * packs up by whatever locale a project configures, not only the codes here.
+ */
+interface UiPackRegistry {
+  [locale: string]: UIStringsOverride;
+}
+
+export const UI_PACKS: UiPackRegistry = {
   ar,
   bg,
   bn,