blume 0.0.0 → 0.1.1

package/src/migrate/fumadocs/content.ts

@@ -0,0 +1,365 @@
+import { existsSync } from "node:fs";
+import { readFile as readFileFromDisk } from "node:fs/promises";
+
+import { dirname, resolve } from "pathe";
+
+import matter from "../../core/frontmatter.ts";
+import { findOpenTagEnd, renameTag, rewriteCallouts } from "../shared.ts";
+
+/**
+ * Source-to-source rewrites that turn Fumadocs-only MDX into idiomatic Blume
+ * markup. Runs once at migration time — no Fumadocs-aware plugins remain in the
+ * Blume runtime.
+ */
+
+// ---------------------------------------------------------------------------
+// Imports
+// ---------------------------------------------------------------------------
+
+const FUMADOCS_IMPORT =
+  /^import\s+[\s\S]*?\s+from\s+["']fumadocs-(?:ui|core|mdx)(?:\/[^"']*)?["'];?[ \t]*\n?/gmu;
+
+/**
+ * Drop `import … from "fumadocs-ui/…"` (and `-core`/`-mdx`) statements. Blume
+ * injects its components globally, so these imports would fail to resolve once
+ * the Fumadocs packages are gone.
+ */
+export const stripFumadocsImports = (source: string): string => {
+  const stripped = source.replace(FUMADOCS_IMPORT, "");
+  // Collapse the blank gap a removed import block leaves behind.
+  return stripped === source ? source : stripped.replaceAll(/\n{3,}/gu, "\n\n");
+};
+
+// ---------------------------------------------------------------------------
+// Callouts
+// ---------------------------------------------------------------------------
+
+/** Fumadocs `<Callout type="X">` values mapped to Blume directive names. */
+const CALLOUT_TYPE_DIRECTIVES: Record<string, string> = {
+  error: "danger",
+  info: "info",
+  note: "note",
+  success: "success",
+  tip: "tip",
+  warn: "warning",
+  warning: "warning",
+};
+
+/**
+ * Convert Fumadocs `<Callout type="info|warn|error|…" title="…">` components
+ * into Blume `:::` directives. A bare `<Callout>` becomes `:::note`; the `icon`
+ * prop is dropped.
+ */
+export const rewriteFumadocsCallouts = (source: string): string =>
+  rewriteCallouts(source, {
+    defaultDirective: "note",
+    tagDirectives: {},
+    tags: ["Callout"],
+    typeDirectives: CALLOUT_TYPE_DIRECTIVES,
+  });
+
+// ---------------------------------------------------------------------------
+// Container component renames
+// ---------------------------------------------------------------------------
+
+/**
+ * Rename Fumadocs container components to their Blume equivalents. The
+ * lookahead in `renameTag` means a longer tag (`Accordions`, `Files`) is never
+ * matched by the rule for its shorter prefix (`Accordion`, `File`), so the
+ * item-level renames run first and the container renames second:
+ *
+ * - `<Cards>` -> `<CardGroup>` (items stay `<Card>`).
+ * - `<Accordions>`/`<Accordion>` -> `<Accordion>`/`<AccordionItem>`.
+ * - `<Files>`/`<Folder>`/`<File>` -> `<FileTree>`/`<TreeFolder>`/`<TreeFile>`.
+ */
+export const rewriteFumadocsContainers = (source: string): string => {
+  let out = renameTag(source, "Cards", "CardGroup");
+  out = renameTag(out, "Accordion", "AccordionItem");
+  out = renameTag(out, "Accordions", "Accordion");
+  out = renameTag(out, "File", "TreeFile");
+  out = renameTag(out, "Folder", "TreeFolder");
+  out = renameTag(out, "Files", "FileTree");
+  return out;
+};
+
+// ---------------------------------------------------------------------------
+// Tabs (items + value -> per-Tab title)
+// ---------------------------------------------------------------------------
+
+const TABS_TAG = /<Tabs(?=[\s/>])/u;
+const TAB_TAG = /<Tab(?=[\s/>])/u;
+const ITEM_LITERAL = /'(?<s>[^']*)'|"(?<d>[^"]*)"|`(?<t>[^`]*)`/gu;
+
+const escapeAttribute = (value: string): string =>
+  value.replaceAll('"', "&quot;");
+
+/** Find the close brace matching the `{` at `open`, or -1 if unterminated. */
+const matchBrace = (source: string, open: number): number => {
+  let depth = 0;
+  for (let index = open; index < source.length; index += 1) {
+    if (source[index] === "{") {
+      depth += 1;
+    } else if (source[index] === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
+};
+
+/** Span of an `items={…}` expression within a tag's attributes, or null. */
+const itemsSpan = (attrs: string): { end: number; start: number } | null => {
+  const match = /\bitems\s*=\s*/u.exec(attrs);
+  if (!match) {
+    return null;
+  }
+  const braceStart = attrs.indexOf("{", match.index + match[0].length);
+  if (braceStart === -1) {
+    return null;
+  }
+  const braceEnd = matchBrace(attrs, braceStart);
+  return braceEnd === -1 ? null : { end: braceEnd, start: match.index };
+};
+
+/** Read the string literals from a Fumadocs `<Tabs items={[…]}>` attribute. */
+const parseItems = (attrs: string): string[] => {
+  const span = itemsSpan(attrs);
+  if (!span) {
+    return [];
+  }
+  const inner = attrs.slice(span.start, span.end + 1);
+  const items: string[] = [];
+  for (const match of inner.matchAll(ITEM_LITERAL)) {
+    items.push(match.groups?.s ?? match.groups?.d ?? match.groups?.t ?? "");
+  }
+  return items;
+};
+
+/** Rebuild a `<Tabs …>` open tag with the `items={…}` attribute removed. */
+const buildTabsOpen = (attrs: string, selfClosing: boolean): string => {
+  const span = itemsSpan(attrs);
+  const withoutItems = span
+    ? attrs.slice(0, span.start) + attrs.slice(span.end + 1)
+    : attrs;
+  const body = withoutItems.replace(/\/\s*$/u, "").trim();
+  const space = body ? ` ${body}` : "";
+  return selfClosing ? `<Tabs${space} />` : `<Tabs${space}>`;
+};
+
+/** Give a single `<Tab …>` open tag a `title`, preferring its own `value`. */
+const titleizeTab = (tag: string, fallback: string | undefined): string => {
+  if (/\btitle\s*=/u.test(tag)) {
+    return tag;
+  }
+  if (/\bvalue\s*=/u.test(tag)) {
+    return tag.replace(/\bvalue(?<eq>\s*=)/u, "title$<eq>");
+  }
+  if (fallback === undefined) {
+    return tag;
+  }
+  return tag.replace(/^<Tab/u, `<Tab title="${escapeAttribute(fallback)}"`);
+};
+
+/**
+ * Find the `</name>` that closes the tag opened at `from` (an index just past
+ * the open tag's `>`), honoring nesting. Returns its start index, or -1.
+ */
+const findMatchingClose = (
+  source: string,
+  from: number,
+  name: string
+): number => {
+  const token = new RegExp(`<${name}(?=[\\s/>])|</${name}>`, "gu");
+  token.lastIndex = from;
+  let depth = 1;
+  for (let match = token.exec(source); match; match = token.exec(source)) {
+    if (match[0].startsWith("</")) {
+      depth -= 1;
+      if (depth === 0) {
+        return match.index;
+      }
+    } else {
+      depth += 1;
+    }
+  }
+  return -1;
+};
+
+/** Title the direct `<Tab>` children of a Tabs block, skipping nested Tabs. */
+const titleizeTabChildren = (inner: string, items: string[]): string => {
+  let output = "";
+  let cursor = 0;
+  let position = 0;
+
+  while (cursor < inner.length) {
+    const rest = inner.slice(cursor);
+    const tab = TAB_TAG.exec(rest);
+    if (!tab) {
+      output += rest;
+      break;
+    }
+    const nested = TABS_TAG.exec(rest);
+    if (nested && nested.index < tab.index) {
+      const start = cursor + nested.index;
+      const openEnd = findOpenTagEnd(inner, start + "<Tabs".length);
+      const close =
+        openEnd === -1 ? -1 : findMatchingClose(inner, openEnd + 1, "Tabs");
+      if (close === -1) {
+        output += inner.slice(cursor);
+        break;
+      }
+      const end = close + "</Tabs>".length;
+      output += inner.slice(cursor, end);
+      cursor = end;
+      continue;
+    }
+    const start = cursor + tab.index;
+    const openEnd = findOpenTagEnd(inner, start + "<Tab".length);
+    if (openEnd === -1) {
+      output += inner.slice(cursor, start + 1);
+      cursor = start + 1;
+      continue;
+    }
+    const tagText = inner.slice(start, openEnd + 1);
+    output +=
+      inner.slice(cursor, start) + titleizeTab(tagText, items[position]);
+    position += 1;
+    cursor = openEnd + 1;
+  }
+
+  return output;
+};
+
+/**
+ * Reshape Fumadocs tabs to Blume's API. Fumadocs declares tab labels on the
+ * parent (`<Tabs items={['npm','pnpm']}>`) and selects with `<Tab value="npm">`;
+ * Blume's `<Tab>` carries its own `title`. Each tab is titled from its `value`
+ * (or the positional `items` entry) and the `items` prop is stripped. Nested
+ * tab groups are handled recursively with their own `items`.
+ */
+export const rewriteFumadocsTabs = (source: string): string => {
+  let output = "";
+  let cursor = 0;
+
+  while (cursor < source.length) {
+    const match = TABS_TAG.exec(source.slice(cursor));
+    if (!match) {
+      output += source.slice(cursor);
+      break;
+    }
+    const start = cursor + match.index;
+    const openEnd = findOpenTagEnd(source, start + "<Tabs".length);
+    if (openEnd === -1) {
+      output += source.slice(cursor, start + 1);
+      cursor = start + 1;
+      continue;
+    }
+    const attrs = source.slice(start + "<Tabs".length, openEnd);
+    const selfClosing = attrs.trimEnd().endsWith("/");
+    output += source.slice(cursor, start);
+
+    if (selfClosing) {
+      output += buildTabsOpen(attrs, true);
+      cursor = openEnd + 1;
+      continue;
+    }
+
+    const close = findMatchingClose(source, openEnd + 1, "Tabs");
+    if (close === -1) {
+      output += source.slice(start, openEnd + 1);
+      cursor = openEnd + 1;
+      continue;
+    }
+    const inner = rewriteFumadocsTabs(source.slice(openEnd + 1, close));
+    output += buildTabsOpen(attrs, false);
+    output += titleizeTabChildren(inner, parseItems(attrs));
+    output += "</Tabs>";
+    cursor = close + "</Tabs>".length;
+  }
+
+  return output;
+};
+
+// ---------------------------------------------------------------------------
+// Includes
+// ---------------------------------------------------------------------------
+
+const INCLUDE = /<include\b[^>]*>(?<path>[\s\S]*?)<\/include>/gu;
+
+interface IncludeOptions {
+  filePath: string;
+  readFile?: (file: string) => Promise<string>;
+  seen?: Set<string>;
+}
+
+/**
+ * Inline Fumadocs `<include>./partial.mdx</include>` references — source-level
+ * includes with no Blume runtime equivalent. The referenced file's frontmatter
+ * is stripped, nested includes are resolved (with a cycle guard), and the path
+ * is resolved relative to the including file. Missing or circular targets are
+ * left untouched and reported.
+ */
+export const inlineFumadocsIncludes = async (
+  source: string,
+  options: IncludeOptions
+): Promise<{ content: string; warnings: string[] }> => {
+  const matches = [...source.matchAll(INCLUDE)];
+  if (matches.length === 0) {
+    return { content: source, warnings: [] };
+  }
+
+  const read = options.readFile ?? ((file) => readFileFromDisk(file, "utf-8"));
+  const seen = options.seen ?? new Set<string>();
+  const warnings: string[] = [];
+  let content = source;
+
+  for (const match of matches) {
+    const rawPath = match.groups?.path?.trim() ?? "";
+    if (!rawPath) {
+      continue;
+    }
+    const target = resolve(dirname(options.filePath), rawPath);
+    if (seen.has(target)) {
+      warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
+      continue;
+    }
+    if (!existsSync(target)) {
+      warnings.push(`<include> target "${rawPath}" not found — left as-is.`);
+      continue;
+    }
+    seen.add(target);
+    // oxlint-disable-next-line no-await-in-loop -- sequential include reads
+    const raw = await read(target);
+    // oxlint-disable-next-line no-await-in-loop -- sequential include reads
+    const nested = await inlineFumadocsIncludes(matter(raw).content.trim(), {
+      ...options,
+      filePath: target,
+      seen,
+    });
+    seen.delete(target);
+    warnings.push(...nested.warnings);
+    content = content.replace(match[0], () => nested.content);
+  }
+
+  return { content, warnings };
+};
+
+// ---------------------------------------------------------------------------
+// Unsupported components
+// ---------------------------------------------------------------------------
+
+/** Fumadocs components with no drop-in Blume equivalent — flagged for review. */
+const UNSUPPORTED_COMPONENTS = [
+  "Banner",
+  "DynamicCodeBlock",
+  "ImageZoom",
+  "InlineTOC",
+];
+
+/** Names of Fumadocs components in `source` that need manual attention. */
+export const unsupportedFumadocsComponents = (source: string): string[] =>
+  UNSUPPORTED_COMPONENTS.filter((name) =>
+    new RegExp(`<${name}\\b`, "u").test(source)
+  );

package/src/migrate/fumadocs/frontmatter.ts

@@ -0,0 +1,18 @@
+import { stripUnknownPageMeta } from "../shared.ts";
+
+/**
+ * Normalize Fumadocs page frontmatter for Blume. Fumadocs' core fields
+ * (`title`, `description`, `icon`) already validate against Blume's page schema
+ * and pass through untouched; Fumadocs-only keys with no equivalent — most
+ * notably `full` (full-width, no-TOC layout) — are dropped by the strict-schema
+ * strip and reported so the author can re-apply them by hand.
+ */
+export const normalizeFumadocsPageMeta = (
+  value: unknown
+): { data: Record<string, unknown>; removed: string[] } => {
+  const data =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? { ...(value as Record<string, unknown>) }
+      : {};
+  return stripUnknownPageMeta(data);
+};

package/src/migrate/fumadocs/groups.ts

@@ -0,0 +1,230 @@
+import { existsSync, statSync } from "node:fs";
+import { mkdir, rename, writeFile } from "node:fs/promises";
+
+import { basename, join } from "pathe";
+
+import { renderMetaModule } from "./meta.ts";
+import type {
+  FumadocsPageItem,
+  FumadocsPagesStructure,
+  FumadocsSection,
+} from "./meta.ts";
+
+/**
+ * Rebuild Fumadocs `---Section---` separators as Blume group folders.
+ *
+ * Fumadocs draws a non-collapsible section heading from a `"---Label---"` entry
+ * in a folder's `pages` array — exactly what a Blume `(Label)/` group folder
+ * renders by default (`display: "flat"`). Blume has no flat-file "separator"
+ * primitive, so the only faithful, non-overriding home for a section is a group
+ * folder: it is route-transparent (the `(Label)` segment is stripped from URLs,
+ * see `core/sources/normalize.ts`) and composes with per-folder `meta.ts`,
+ * unlike a global `navigation.sidebar` override (which would disable every other
+ * folder's meta site-wide).
+ *
+ * The reshape runs against the already-migrated `docs/` tree, so each `pages`
+ * entry is resolved to a real page file or folder before it is moved. A section
+ * that is a single folder is left in place (wrapping it would double the
+ * heading); links have no file to move and are dropped with a warning.
+ */
+
+const PAGE_EXTS = [".mdx", ".md"];
+const WORD_SPLIT = /[-_]/u;
+const PATH_SEP = /[/\\]/u;
+
+interface ResolvedEntry {
+  kind: "file" | "folder";
+  path: string;
+}
+
+const isDirectory = (path: string): boolean => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/** Resolve a `pages` name to its on-disk page file or folder under `docsDir`. */
+const resolveEntry = (docsDir: string, name: string): ResolvedEntry | null => {
+  for (const ext of PAGE_EXTS) {
+    const file = join(docsDir, `${name}${ext}`);
+    if (existsSync(file)) {
+      return { kind: "file", path: file };
+    }
+  }
+  const folder = join(docsDir, name);
+  return isDirectory(folder) ? { kind: "folder", path: folder } : null;
+};
+
+const humanize = (name: string): string =>
+  name
+    .split(WORD_SPLIT)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+
+const linkWarning = (item: { href: string; text: string }): string =>
+  `Dropped sidebar link "${item.text}" (${item.href}) — add it to navbar.links manually.`;
+
+const extractWarning = (name: string): string =>
+  `Sidebar extract "...${name}" became a normal "${name}" group (its pages are not flattened into the parent).`;
+
+export interface GroupReshapeResult {
+  /** Ordering keys for the parent folder's `meta.ts` `pages`. */
+  order: string[];
+  warnings: string[];
+}
+
+/** Record an in-place item's ordering key (lead items, or an ungroupable run). */
+const addUngroupedItem = (
+  item: FumadocsPageItem,
+  order: string[],
+  warnings: string[]
+): void => {
+  if (item.kind === "link") {
+    warnings.push(linkWarning(item));
+    return;
+  }
+  if (item.kind === "extract") {
+    warnings.push(extractWarning(item.name));
+  }
+  order.push(item.name);
+};
+
+/** A section of one folder keeps its place without a wrapping group folder. */
+const reshapeSingleFolderSection = (
+  section: FumadocsSection,
+  only: FumadocsPageItem & { kind: "extract" | "ref" },
+  order: string[],
+  warnings: string[]
+): void => {
+  order.push(only.name);
+  if (humanize(only.name).toLowerCase() !== section.label.toLowerCase()) {
+    warnings.push(
+      `Section "${section.label}" wraps folder "${only.name}"; set that folder's meta title to "${section.label}" to make the heading match.`
+    );
+  }
+  if (only.kind === "extract") {
+    warnings.push(extractWarning(only.name));
+  }
+};
+
+/** Move one section item into the group folder; return its ordering key. */
+const moveItemIntoGroup = async (
+  item: FumadocsPageItem,
+  docsDir: string,
+  groupDir: string,
+  label: string,
+  warnings: string[]
+): Promise<string | null> => {
+  if (item.kind === "link") {
+    warnings.push(linkWarning(item));
+    return null;
+  }
+  const resolved = resolveEntry(docsDir, item.name);
+  if (!resolved) {
+    warnings.push(
+      `Sidebar entry "${item.name}" in section "${label}" matched no page or folder; skipped.`
+    );
+    return null;
+  }
+  const dest = join(groupDir, basename(resolved.path));
+  if (existsSync(dest)) {
+    warnings.push(
+      `Skipped moving "${item.name}" into section "${label}" (target already exists).`
+    );
+    return null;
+  }
+  await mkdir(groupDir, { recursive: true });
+  await rename(resolved.path, dest);
+  if (item.kind === "extract") {
+    warnings.push(extractWarning(item.name));
+  }
+  return item.name;
+};
+
+const reshapeSection = async (
+  section: FumadocsSection,
+  docsDir: string,
+  order: string[],
+  warnings: string[]
+): Promise<void> => {
+  const movable = section.items.filter((item) => item.kind !== "link");
+
+  // A lone folder already renders as its own group; wrapping it in a `(Label)/`
+  // folder would stack two headings, so leave it in place.
+  if (movable.length === 1) {
+    const [only] = movable as [FumadocsPageItem & { kind: "extract" | "ref" }];
+    if (resolveEntry(docsDir, only.name)?.kind === "folder") {
+      reshapeSingleFolderSection(section, only, order, warnings);
+      return;
+    }
+  }
+
+  if (PATH_SEP.test(section.label)) {
+    warnings.push(
+      `Section "${section.label}" has a slash in its name and can't become a group folder; its pages stay ungrouped.`
+    );
+    for (const item of section.items) {
+      addUngroupedItem(item, order, warnings);
+    }
+    return;
+  }
+
+  const groupDir = join(docsDir, `(${section.label})`);
+  const sectionKeys: string[] = [];
+  for (const item of section.items) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential moves into one group
+    const key = await moveItemIntoGroup(
+      item,
+      docsDir,
+      groupDir,
+      section.label,
+      warnings
+    );
+    if (key) {
+      sectionKeys.push(key);
+    }
+  }
+
+  // Nothing movable (e.g. a link-only section) — drop the empty heading.
+  if (sectionKeys.length === 0) {
+    return;
+  }
+
+  // The group folder's key in the nav is its label, so order it by label.
+  order.push(section.label);
+  // Preserve the authored order of the section's pages.
+  if (sectionKeys.length > 1) {
+    await writeFile(
+      join(groupDir, "meta.ts"),
+      renderMetaModule({ pages: sectionKeys }),
+      "utf-8"
+    );
+  }
+};
+
+/**
+ * Reshape a parsed `pages` structure into group folders under `docsDir`,
+ * returning the parent folder's `meta.ts` page ordering and any warnings. Items
+ * are moved within the already-migrated `docs/` tree, so this must run after the
+ * pages have been moved out of `content/docs`.
+ */
+export const reshapeFumadocsGroups = async (
+  structure: FumadocsPagesStructure,
+  docsDir: string
+): Promise<GroupReshapeResult> => {
+  const order: string[] = [];
+  const warnings: string[] = [];
+
+  for (const item of structure.lead) {
+    addUngroupedItem(item, order, warnings);
+  }
+  for (const section of structure.sections) {
+    // oxlint-disable-next-line no-await-in-loop -- sections share `docsDir` state
+    await reshapeSection(section, docsDir, order, warnings);
+  }
+
+  return { order, warnings };
+};