blume 0.5.3 → 0.6.0

package/src/migrate/fumadocs/content.ts

@@ -1,376 +0,0 @@
-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,
-  isInsideRoot,
-  renameTag,
-  rewriteCallouts,
-  stripImports,
-} 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 =>
-  stripImports(source, FUMADOCS_IMPORT);
-
-// ---------------------------------------------------------------------------
-// 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>;
-  /** Docs root the include must stay within; targets escaping it are skipped. */
-  root: 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 (!isInsideRoot(options.root, target)) {
-      warnings.push(
-        `<include> target "${rawPath}" is outside the docs tree — left as-is.`
-      );
-      continue;
-    }
-    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

@@ -1,18 +0,0 @@
-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

@@ -1,237 +0,0 @@
-import { existsSync, statSync } from "node:fs";
-import { mkdir, rename, writeFile } from "node:fs/promises";
-
-import { basename, join } from "pathe";
-
-import { isInsideRoot } from "../shared.ts";
-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 => {
-  // A `pages` entry is author-controlled; reject any that escapes `docsDir`
-  // (e.g. `"../../victim"`) so the later `rename` can't move a file out of the
-  // docs tree.
-  if (!isInsideRoot(docsDir, join(docsDir, name))) {
-    return 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 };
-};