blume 0.5.3 → 0.5.4

package/src/migrate/fumadocs/index.ts

@@ -1,355 +0,0 @@
-import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-
-import { dirname, join, relative } from "pathe";
-import { glob } from "tinyglobby";
-
-import matter from "../../core/frontmatter.ts";
-import { ensureGitignore } from "../../core/gitignore.ts";
-import type { FolderMeta } from "../../core/schema.ts";
-import {
-  leftoverFiles,
-  rewriteFrameworkScripts,
-  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 { reshapeFumadocsGroups } from "./groups.ts";
-import {
-  parseFumadocsPages,
-  renderMetaModule,
-  translateFumadocsMeta,
-  translateFumadocsSelfMeta,
-} 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/**"];
-
-/**
- * Old Next/Fumadocs scaffolding a migration leaves behind. Blume can't safely
- * auto-delete these (they may hold custom code), so the ones that exist are
- * surfaced as a "safe to delete" checklist once the migration is verified.
- */
-const FUMADOCS_LEFTOVERS = [
-  "next.config.ts",
-  "next.config.mjs",
-  "next.config.js",
-  "source.config.ts",
-  "source.config.mjs",
-  "source.config.js",
-  "mdx-components.tsx",
-  "next-env.d.ts",
-  "app",
-];
-
-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,
-    root: base,
-  });
-  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,
-  };
-};
-
-/**
- * Write a `FolderMeta` to `dest` unless it already exists. `handled` tells the
- * caller whether the source `meta.json` is safe to delete — a skipped write
- * (target exists) must keep the source, or its title/ordering is lost with
- * nowhere to recover it from.
- */
-const writeMeta = async (
-  dest: string,
-  meta: FolderMeta,
-  rel: string,
-  warnings: string[]
-): Promise<{ handled: boolean; warnings: string[] }> => {
-  if (Object.keys(meta).length === 0) {
-    return { handled: true, warnings };
-  }
-  if (existsSync(dest)) {
-    return {
-      handled: false,
-      warnings: [
-        ...warnings,
-        `Skipped ${rel} (target already exists); the source file was kept — merge it into the existing meta.ts by hand.`,
-      ],
-    };
-  }
-  await mkdir(dirname(dest), { recursive: true });
-  await writeFile(dest, renderMetaModule(meta), "utf-8");
-  return { handled: true, warnings };
-};
-
-/** 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 dir = dirname(rel) === "." ? "" : dirname(rel);
-  const docsDir = join(root, "docs", dir);
-  const dest = join(docsDir, "meta.ts");
-
-  // A `pages` array with `---Section---` separators can't round-trip through a
-  // flat `meta.ts` ordering, so rebuild its sections as group folders instead.
-  const structure = parseFumadocsPages((parsed as { pages?: unknown }).pages);
-  if (structure.hasSections && !existsSync(dest)) {
-    const self = translateFumadocsSelfMeta(parsed);
-    const reshape = await reshapeFumadocsGroups(structure, docsDir);
-    const meta: FolderMeta = { ...self.meta };
-    if (reshape.order.length > 0) {
-      meta.pages = reshape.order;
-    }
-    const result = await writeMeta(dest, meta, rel, [
-      ...self.warnings,
-      ...reshape.warnings,
-    ]);
-    if (result.handled) {
-      await rm(abs, { force: true });
-    }
-    return result.warnings;
-  }
-
-  const { meta, warnings } = translateFumadocsMeta(parsed);
-  const result = await writeMeta(dest, meta, rel, warnings);
-  if (result.handled) {
-    await rm(abs, { force: true });
-  }
-  return result.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);
-  // Convert metas deepest-first and sequentially: a parent's group-folder
-  // reshape can move a child folder, so the child's own reshape must finish
-  // first (and the two can't race over the same `docs/` paths).
-  const orderedMetas = metaFiles.toSorted(
-    (a, b) => b.split("/").length - a.split("/").length
-  );
-  const metaWarnings: string[] = [];
-  for (const abs of orderedMetas) {
-    // oxlint-disable-next-line no-await-in-loop -- sequential to avoid move races
-    metaWarnings.push(...(await convertMeta(abs, base, root)));
-  }
-
-  await writeBlumeConfig(root, config);
-  const cleanupWarnings = await cleanupSourceDirs(root);
-
-  // Tear down the old Next/Fumadocs scaffolding so the project builds as Blume:
-  // repoint the npm scripts, ignore Blume's outputs, and list the leftover
-  // framework files to delete by hand.
-  const scriptsRewritten = await rewriteFrameworkScripts(
-    root,
-    /\bnext\b/u,
-    /fumadocs/u
-  );
-  const gitignoreAdded = await ensureGitignore(root, [".blume/", "dist/"]);
-  const leftovers = leftoverFiles(root, FUMADOCS_LEFTOVERS);
-
-  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(", ")}.`
-    );
-  }
-  if (scriptsRewritten) {
-    warnings.push("Repointed the dev/build/start scripts at the Blume CLI.");
-  }
-  if (gitignoreAdded.length > 0) {
-    warnings.push(`Added ${gitignoreAdded.join(", ")} to .gitignore.`);
-  }
-  if (leftovers.length > 0) {
-    warnings.push(
-      `Safe to delete once the migration looks right: ${leftovers.join(", ")}. Also drop the \`next\` plugin from tsconfig.json and the \`.next\`/\`.source\` lines from .gitignore.`
-    );
-  }
-  warnings.push("Review blume.config.ts and the generated meta.ts files.");
-
-  return { moved: pages.moved, warnings };
-};

package/src/migrate/fumadocs/meta.ts

@@ -1,244 +0,0 @@
-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; `"...folder"` (the *extract*
- *   operator, which inlines a folder's children) keeps the folder's place in the
- *   ordering as a plain `"folder"` key and warns that it renders as a normal
- *   group rather than flattened; `"---Section---"` separators and `"[Text](url)"`
- *   links have no folder-meta home and are dropped with a warning.
- *
- * When a `pages` array carries `---Section---` separators, the migrator instead
- * takes the *structural* path ({@link parseFumadocsPages} + the group-folder
- * reshape in `index.ts`), which rebuilds each section as a Blume group folder
- * rather than flattening it through `filterPages`.
- */
-
-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 = "...";
-/** Fumadocs *extract* operator: `...folder` inlines that folder's children. */
-const EXTRACT = /^\.\.\.(?<folder>.+)$/u;
-
-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 extract = EXTRACT.exec(value);
-    if (extract) {
-      // Blume has no "flatten a folder's children inline" sidebar primitive, but
-      // the folder is a sibling here, so keep its position in the ordering and
-      // let it render as a normal group.
-      const folder = extract.groups?.folder?.trim() ?? "";
-      if (folder) {
-        pages.push(folder);
-        warnings.push(
-          `Sidebar extract "...${folder}" became a normal "${folder}" group (its pages are not flattened into the parent).`
-        );
-      }
-      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[];
-}
-
-/** Render a Blume `meta.ts` module source for a `FolderMeta`. */
-export const renderMetaModule = (meta: FolderMeta): string =>
-  `import { defineMeta } from "blume";\n\nexport default defineMeta(${JSON.stringify(meta, null, 2)});\n`;
-
-/**
- * Translate a folder's own title/icon/display fields — everything in a Fumadocs
- * `meta.json` *except* the `pages` ordering. Split out from
- * {@link translateFumadocsMeta} so the structural path (which reshapes `pages`
- * into group folders) can reuse the self fields without the flat `pages` array.
- */
-export const translateFumadocsSelfMeta = (
-  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."
-    );
-  }
-
-  return { meta, warnings };
-};
-
-/** Map a parsed Fumadocs `meta.json` object onto a Blume `FolderMeta`. */
-export const translateFumadocsMeta = (
-  value: unknown
-): FumadocsMetaConversion => {
-  const { meta, warnings } = translateFumadocsSelfMeta(value);
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    const { pages, warnings: pageWarnings } = filterPages(
-      (value as FumadocsMeta).pages
-    );
-    if (pages.length > 0) {
-      meta.pages = pages;
-    }
-    warnings.push(...pageWarnings);
-  }
-  return { meta, warnings };
-};
-
-// ---------------------------------------------------------------------------
-// Structural pages (separators -> sections)
-// ---------------------------------------------------------------------------
-
-/**
- * One entry in a Fumadocs `pages` array, after classification: a `ref` (a plain
- * page or folder name), an `extract` (`...folder`, whose children Fumadocs
- * inlines), or a `link` (`[Text](url)`).
- */
-export type FumadocsPageItem =
-  | { kind: "extract"; name: string }
-  | { kind: "link"; href: string; text: string }
-  | { kind: "ref"; name: string };
-
-/** A run of items under one `---Label---` separator. */
-export interface FumadocsSection {
-  items: FumadocsPageItem[];
-  label: string;
-}
-
-export interface FumadocsPagesStructure {
-  /** Whether any `---Section---` separator was present. */
-  hasSections: boolean;
-  /** Items before the first separator; they stay at the folder's top level. */
-  lead: FumadocsPageItem[];
-  sections: FumadocsSection[];
-}
-
-/**
- * Parse a Fumadocs `pages` array into its structural shape: the lead items
- * (before any separator) and the sections each `---Label---` introduces. Unlike
- * {@link filterPages}, separators are preserved (as section boundaries) so the
- * migrator can rebuild them as Blume group folders. The rest marker (`"..."`) is
- * dropped — Blume appends unlisted pages by default.
- */
-export const parseFumadocsPages = (raw: unknown): FumadocsPagesStructure => {
-  const lead: FumadocsPageItem[] = [];
-  const sections: FumadocsSection[] = [];
-  if (!Array.isArray(raw)) {
-    return { hasSections: false, lead, sections };
-  }
-
-  let current: FumadocsSection | null = null;
-  const push = (item: FumadocsPageItem): void => {
-    (current ? current.items : lead).push(item);
-  };
-
-  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) {
-      current = {
-        items: [],
-        label: separator.groups?.label?.trim() || "Section",
-      };
-      sections.push(current);
-      continue;
-    }
-    const extract = EXTRACT.exec(value);
-    if (extract) {
-      const name = extract.groups?.folder?.trim();
-      if (name) {
-        push({ kind: "extract", name });
-      }
-      continue;
-    }
-    const link = LINK.exec(value);
-    if (link) {
-      push({
-        href: link.groups?.href ?? "",
-        kind: "link",
-        text: link.groups?.text ?? "",
-      });
-      continue;
-    }
-    push({ kind: "ref", name: value });
-  }
-
-  return { hasSections: sections.length > 0, lead, sections };
-};

package/src/migrate/migrate.ts

@@ -1,53 +0,0 @@
-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,
-};

package/src/migrate/mintlify/assets.ts

@@ -1,46 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-
-/** Asset paths referenced by the resolved config (logo, favicon, backgrounds). */
-const assetRefs = (config: BlumeConfig): unknown[] => {
-  const refs: unknown[] = ["/images"];
-  const logo = config.logo as
-    | string
-    | { dark?: string; light?: string }
-    | undefined;
-  if (typeof logo === "string") {
-    refs.push(logo);
-  } else if (logo) {
-    refs.push(logo.light, logo.dark);
-  }
-  const favicon = config.favicon as
-    | string
-    | { dark?: string; light?: string }
-    | undefined;
-  if (typeof favicon === "string") {
-    refs.push(favicon);
-  } else if (favicon) {
-    refs.push(favicon.light, favicon.dark);
-  }
-  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
-  return refs;
-};
-
-/**
- * Top-level path segments referenced as static assets by a Mintlify config
- * (the conventional `/images`, plus logo/favicon/background paths). These are
- * the root-served folders Mintlify exposes at the site root; Blume serves them
- * via `content.assets` (bridge) or relocates them under `public/` (migrator).
- */
-export const assetSegments = (config: BlumeConfig): string[] => {
-  const segments = new Set<string>();
-  for (const ref of assetRefs(config)) {
-    if (typeof ref !== "string" || !ref.startsWith("/")) {
-      continue;
-    }
-    const [segment] = ref.replace(/^\/+/u, "").split("/");
-    if (segment) {
-      segments.add(segment);
-    }
-  }
-  return [...segments];
-};