blume 0.0.0 → 0.1.0

package/src/migrate/fumadocs/index.ts

@@ -0,0 +1,252 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+
+import matter from "gray-matter";
+import { dirname, join, relative } from "pathe";
+import { glob } from "tinyglobby";
+
+import { writeBlumeConfig } from "../shared.ts";
+import { loadFumadocsConfig } from "./config.ts";
+import {
+  inlineFumadocsIncludes,
+  rewriteFumadocsCallouts,
+  rewriteFumadocsContainers,
+  rewriteFumadocsTabs,
+  stripFumadocsImports,
+  unsupportedFumadocsComponents,
+} from "./content.ts";
+import { normalizeFumadocsPageMeta } from "./frontmatter.ts";
+import { translateFumadocsMeta } from "./meta.ts";
+
+export interface FumadocsMigrationResult {
+  moved: number;
+  warnings: string[];
+}
+
+/** Fumadocs keeps documentation under `content/docs/`. */
+const SOURCE_DIR = "content/docs";
+const PAGE_GLOB = "**/*.{md,mdx}";
+const META_GLOB = "**/meta.json";
+const IGNORE = ["**/node_modules/**"];
+
+interface PageResult {
+  includeWarnings: string[];
+  moved: number;
+  removed: string[];
+  skipped: string | null;
+  unsupported: string[];
+}
+
+/** Rewrite a single page to idiomatic Blume MDX and move it into `docs/`. */
+const movePage = async (
+  abs: string,
+  base: string,
+  root: string
+): Promise<PageResult> => {
+  const rel = relative(base, abs);
+  const dest = join(root, "docs", rel);
+  if (existsSync(dest)) {
+    return {
+      includeWarnings: [],
+      moved: 0,
+      removed: [],
+      skipped: rel,
+      unsupported: [],
+    };
+  }
+
+  const raw = await readFile(abs, "utf-8");
+  const included = await inlineFumadocsIncludes(raw, { filePath: abs });
+  let text = stripFumadocsImports(included.content);
+  text = rewriteFumadocsCallouts(text);
+  text = rewriteFumadocsContainers(text);
+  text = rewriteFumadocsTabs(text);
+  const unsupported = unsupportedFumadocsComponents(text);
+
+  const parsed = matter(text);
+  const { data, removed } = normalizeFumadocsPageMeta(parsed.data);
+  const content =
+    Object.keys(data).length > 0
+      ? matter.stringify(parsed.content, data)
+      : parsed.content;
+
+  await mkdir(dirname(dest), { recursive: true });
+  await writeFile(dest, content, "utf-8");
+  await rm(abs, { force: true });
+  return {
+    includeWarnings: included.warnings,
+    moved: 1,
+    removed,
+    skipped: null,
+    unsupported,
+  };
+};
+
+/** Convert one `meta.json` into a typed `meta.ts`, or relocate it if unparseable. */
+const convertMeta = async (
+  abs: string,
+  base: string,
+  root: string
+): Promise<string[]> => {
+  const rel = relative(base, abs);
+  const raw = await readFile(abs, "utf-8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    const dest = join(root, "docs", rel);
+    if (existsSync(dest)) {
+      return [`Skipped ${rel} (target already exists)`];
+    }
+    await mkdir(dirname(dest), { recursive: true });
+    await rename(abs, dest);
+    return [
+      `Could not parse ${rel}; moved as-is — convert it to meta.ts by hand.`,
+    ];
+  }
+
+  const { meta, warnings } = translateFumadocsMeta(parsed);
+  const dir = dirname(rel) === "." ? "" : dirname(rel);
+  if (Object.keys(meta).length > 0) {
+    const dest = join(root, "docs", dir, "meta.ts");
+    if (existsSync(dest)) {
+      await rm(abs, { force: true });
+      return [...warnings, `Skipped ${rel} (target already exists)`];
+    }
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(
+      dest,
+      `import { defineMeta } from "blume";\n\nexport default defineMeta(${JSON.stringify(meta, null, 2)});\n`,
+      "utf-8"
+    );
+  }
+  await rm(abs, { force: true });
+  return warnings;
+};
+
+interface PageSummary {
+  includeWarnings: string[];
+  moved: number;
+  removedKeys: string[];
+  skipped: string[];
+  unsupported: string[];
+}
+
+const summarizePages = (results: PageResult[]): PageSummary => {
+  let moved = 0;
+  const removedKeys = new Set<string>();
+  const unsupported = new Set<string>();
+  const includeWarnings: string[] = [];
+  const skipped: string[] = [];
+  for (const result of results) {
+    moved += result.moved;
+    if (result.skipped) {
+      skipped.push(result.skipped);
+    }
+    includeWarnings.push(...result.includeWarnings);
+    for (const key of result.removed) {
+      removedKeys.add(key);
+    }
+    for (const name of result.unsupported) {
+      unsupported.add(name);
+    }
+  }
+  return {
+    includeWarnings,
+    moved,
+    removedKeys: [...removedKeys],
+    skipped,
+    unsupported: [...unsupported],
+  };
+};
+
+/** Remove `content/docs` and `content` once emptied; warn about leftovers. */
+const cleanupSourceDirs = async (root: string): Promise<string[]> => {
+  const docs = join(root, "content", "docs");
+  if (existsSync(docs)) {
+    const remaining = await glob(["**/*"], { cwd: docs, dot: true });
+    if (remaining.length > 0) {
+      return [
+        `Kept ${remaining.length} non-page file(s) under content/docs; move them into docs/ manually.`,
+      ];
+    }
+    await rm(docs, { force: true, recursive: true });
+  }
+  const content = join(root, "content");
+  if (existsSync(content)) {
+    const remaining = await glob(["**/*"], { cwd: content, dot: true });
+    if (remaining.length === 0) {
+      await rm(content, { force: true, recursive: true });
+    }
+  }
+  return [];
+};
+
+/**
+ * Migrate a Fumadocs project to Blume. Moves every `content/docs` page into
+ * `docs/`, rewrites Fumadocs MDX (callouts to directives, `<Cards>`/
+ * `<Accordions>`/`<Files>` to their Blume equivalents, `<Tabs items>` to
+ * per-`<Tab>` titles, and `<include>`s inlined), and converts each `meta.json`
+ * into a typed `meta.ts`. The `loader({ baseUrl })` route prefix is preserved
+ * via a `content.sources` filesystem source.
+ */
+export const migrateFumadocsProject = async (
+  root: string
+): Promise<FumadocsMigrationResult> => {
+  const { config, warnings: configWarnings } = await loadFumadocsConfig(root);
+
+  const base = join(root, SOURCE_DIR);
+  if (!existsSync(base)) {
+    await writeBlumeConfig(root, config);
+    return {
+      moved: 0,
+      warnings: [
+        `No Fumadocs content directory (${SOURCE_DIR}) found; wrote a default config.`,
+      ],
+    };
+  }
+
+  const pageFiles = await glob([PAGE_GLOB], {
+    absolute: true,
+    cwd: base,
+    ignore: IGNORE,
+  });
+  const metaFiles = await glob([META_GLOB], {
+    absolute: true,
+    cwd: base,
+    ignore: IGNORE,
+  });
+
+  const pageResults = await Promise.all(
+    pageFiles.map((abs) => movePage(abs, base, root))
+  );
+  const pages = summarizePages(pageResults);
+  const metaResults = await Promise.all(
+    metaFiles.map((abs) => convertMeta(abs, base, root))
+  );
+  const metaWarnings = metaResults.flat();
+
+  await writeBlumeConfig(root, config);
+  const cleanupWarnings = await cleanupSourceDirs(root);
+
+  const warnings = [
+    ...configWarnings,
+    ...metaWarnings,
+    ...pages.includeWarnings,
+    ...pages.skipped.map((rel) => `Skipped ${rel} (target already exists)`),
+    ...cleanupWarnings,
+  ];
+  if (pages.removedKeys.length > 0) {
+    warnings.push(
+      `Dropped unsupported page frontmatter keys: ${pages.removedKeys.join(", ")}.`
+    );
+  }
+  if (pages.unsupported.length > 0) {
+    warnings.push(
+      `Components without a drop-in Blume equivalent need manual review: ${pages.unsupported.join(", ")}.`
+    );
+  }
+  warnings.push("Review blume.config.ts and the generated meta.ts files.");
+
+  return { moved: pages.moved, warnings };
+};

package/src/migrate/fumadocs/meta.ts

@@ -0,0 +1,114 @@
+import type { FolderMeta } from "../../core/schema.ts";
+
+/**
+ * Translate a Fumadocs folder `meta.json` into a Blume `FolderMeta` (`meta.ts`).
+ * Unlike Nextra, Fumadocs declares a folder's own title/icon/ordering in *that
+ * folder's* `meta.json`, so the mapping is self-contained. Fumadocs-only
+ * concepts with no Blume equivalent are dropped and reported:
+ *
+ * - `defaultOpen` -> `collapsed` (inverted) + `display: "group"` (collapsible).
+ * - `root: true` -> `display: "page"` (the closest analogue to a page-tree root).
+ * - `description` -> dropped (folders carry no description in Blume).
+ * - `pages` entries: plain slugs are kept as ordering; `"..."` (the rest marker,
+ *   already Blume's default) is dropped silently; `"---Section---"` separators
+ *   and `"[Text](url)"` links have no folder-meta home and are dropped with a
+ *   warning.
+ */
+
+interface FumadocsMeta {
+  defaultOpen?: unknown;
+  description?: unknown;
+  icon?: unknown;
+  pages?: unknown;
+  root?: unknown;
+  title?: unknown;
+}
+
+const SEPARATOR = /^---(?<label>.*)---$/u;
+const LINK = /^(?:\[[^\]]*\])?\[(?<text>[^\]]*)\]\((?<href>[^)]*)\)$/u;
+const REST = "...";
+
+interface PagesResult {
+  pages: string[];
+  warnings: string[];
+}
+
+const filterPages = (raw: unknown): PagesResult => {
+  if (!Array.isArray(raw)) {
+    return { pages: [], warnings: [] };
+  }
+
+  const pages: string[] = [];
+  const warnings: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const value = entry.trim();
+    if (value === REST || value === "") {
+      continue;
+    }
+    const separator = SEPARATOR.exec(value);
+    if (separator) {
+      const label = separator.groups?.label?.trim();
+      warnings.push(
+        `Dropped sidebar separator "${label || value}" — recreate it with a sidebar group if needed.`
+      );
+      continue;
+    }
+    const link = LINK.exec(value);
+    if (link) {
+      warnings.push(
+        `Dropped sidebar link "${link.groups?.text}" (${link.groups?.href}) — add it to navbar.links manually.`
+      );
+      continue;
+    }
+    pages.push(value);
+  }
+
+  return { pages, warnings };
+};
+
+export interface FumadocsMetaConversion {
+  meta: FolderMeta;
+  warnings: string[];
+}
+
+/** Map a parsed Fumadocs `meta.json` object onto a Blume `FolderMeta`. */
+export const translateFumadocsMeta = (
+  value: unknown
+): FumadocsMetaConversion => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { meta: {}, warnings: [] };
+  }
+
+  const source = value as FumadocsMeta;
+  const meta: FolderMeta = {};
+  const warnings: string[] = [];
+
+  if (typeof source.title === "string") {
+    meta.title = source.title;
+  }
+  if (typeof source.icon === "string") {
+    meta.icon = source.icon;
+  }
+  if (source.root === true) {
+    meta.display = "page";
+  } else if (typeof source.defaultOpen === "boolean") {
+    meta.display = "group";
+    meta.collapsed = !source.defaultOpen;
+  }
+  if (typeof source.description === "string") {
+    warnings.push(
+      "Dropped folder `description` — Blume folders have no description field."
+    );
+  }
+
+  const { pages, warnings: pageWarnings } = filterPages(source.pages);
+  if (pages.length > 0) {
+    meta.pages = pages;
+  }
+  warnings.push(...pageWarnings);
+
+  return { meta, warnings };
+};

package/src/migrate/migrate.ts

@@ -0,0 +1,53 @@
+import { migrateFumadocsProject } from "./fumadocs/index.ts";
+import { migrateMintlifyProject } from "./mintlify/index.ts";
+import { migrateNextraProject } from "./nextra/index.ts";
+import { migrateStarlightProject } from "./starlight/index.ts";
+
+export interface MigrationResult {
+  moved: number;
+  warnings: string[];
+}
+
+/**
+ * Migrate a Mintlify project (`docs.json`/`mint.json` + MDX). Translates the
+ * config, rewrites pages to idiomatic Blume MDX in place, and relocates assets.
+ * Unlike the other migrators, content stays at the project root.
+ */
+export const migrateMintlify = (root: string): Promise<MigrationResult> =>
+  migrateMintlifyProject(root);
+
+/**
+ * Migrate a Nextra project (`content/` or `pages/` + `_meta` files). Moves pages
+ * into `docs/`, rewrites `<Callout>`s to directives, and converts every `_meta`
+ * into a typed `meta.ts`, preserving navigation order and titles.
+ */
+export const migrateNextra = (root: string): Promise<MigrationResult> =>
+  migrateNextraProject(root);
+
+/**
+ * Migrate a Fumadocs project (`content/docs` + `meta.json`). Moves pages into
+ * `docs/`, rewrites Fumadocs MDX (callouts, `<Cards>`/`<Accordions>`/`<Files>`,
+ * `<Tabs items>`, `<include>`) to idiomatic Blume markup, converts every
+ * `meta.json` into a typed `meta.ts`, and preserves the `/docs` route prefix.
+ */
+export const migrateFumadocs = (root: string): Promise<MigrationResult> =>
+  migrateFumadocsProject(root);
+
+/**
+ * Migrate a Starlight project (`src/content/docs` + `astro.config.*`). Translates
+ * the `starlight({...})` options into `blume.config.ts` and rewrites each page to
+ * idiomatic Blume MDX in place (asides → directives, component renames,
+ * frontmatter mapping). Content stays under `src/content/docs`.
+ */
+export const migrateStarlight = (root: string): Promise<MigrationResult> =>
+  migrateStarlightProject(root);
+
+export const migrators: Record<
+  string,
+  (root: string) => Promise<MigrationResult>
+> = {
+  fumadocs: migrateFumadocs,
+  mintlify: migrateMintlify,
+  nextra: migrateNextra,
+  starlight: migrateStarlight,
+};