blume 0.5.2 → 0.5.4

package/src/migrate/mintlify/transform.ts

@@ -1,82 +0,0 @@
-import matter from "../../core/frontmatter.ts";
-import { stripUnknownPageMeta } from "../shared.ts";
-import {
-  rewriteMintlifyAccordions,
-  rewriteMintlifyCallouts,
-  rewriteMintlifyExampleBlocks,
-  rewriteSnippetImports,
-  unsupportedMintlifyComponents,
-} from "./content.ts";
-import { normalizeMintlifyPageMeta } from "./frontmatter.ts";
-import { rewriteMintlifySvgIconProps } from "./icons.ts";
-import {
-  rewriteMintlifyGlobalVariables,
-  rewriteMintlifyMarkdownSnippets,
-  rewriteMintlifySnippetVariables,
-  rewriteMintlifyUserVariable,
-} from "./snippets.ts";
-
-const USER_REFERENCE = /\{[^{}]*\buser\b/u;
-
-/** The outcome of transforming a single Mintlify page to Blume MDX. */
-export interface MintlifyTransformResult {
-  /** Component snippet imports kept (rewritten to relative paths). */
-  components: string[];
-  /** The rewritten file text, including normalized frontmatter. */
-  content: string;
-  /** Frontmatter keys dropped because Blume has no equivalent. */
-  removed: string[];
-  /** Components encountered that have no Blume equivalent. */
-  unsupported: string[];
-}
-
-/**
- * Apply the per-file source transforms that turn Mintlify MDX into Blume MDX:
- * inline snippets and variables, rewrite callouts (`<Note>` → `:::note`),
- * example blocks, and inline-SVG icon props, then normalize frontmatter. Pure
- * text-in/text-out (snippets read from disk relative to `root`), so both the
- * one-shot migrator and the live bridge source share identical behavior.
- */
-export const transformMintlifyContent = async (
-  raw: string,
-  options: { filePath: string; root: string; variables: Record<string, string> }
-): Promise<MintlifyTransformResult> => {
-  let text = await rewriteMintlifyMarkdownSnippets(raw, {
-    filePath: options.filePath,
-    root: options.root,
-  });
-  text = await rewriteMintlifySnippetVariables(text, {
-    filePath: options.filePath,
-    root: options.root,
-  });
-  text = rewriteMintlifyGlobalVariables(text, options.variables);
-  if (USER_REFERENCE.test(text)) {
-    text = rewriteMintlifyUserVariable(text);
-  }
-  const snippetImports = rewriteSnippetImports(text, {
-    filePath: options.filePath,
-    root: options.root,
-  });
-  text = snippetImports.source;
-  text = rewriteMintlifySvgIconProps(text);
-  text = rewriteMintlifyExampleBlocks(text);
-  text = rewriteMintlifyAccordions(text);
-  text = rewriteMintlifyCallouts(text);
-
-  const unsupported = unsupportedMintlifyComponents(text);
-
-  const parsed = matter(text);
-  const mapped = normalizeMintlifyPageMeta(parsed.data);
-  const { data, removed } = stripUnknownPageMeta(mapped);
-  const content =
-    Object.keys(data).length > 0
-      ? matter.stringify(parsed.content, data)
-      : parsed.content;
-
-  return {
-    components: snippetImports.components,
-    content,
-    removed,
-    unsupported,
-  };
-};

package/src/migrate/nextra/content.ts

@@ -1,46 +0,0 @@
-import { rewriteCallouts } from "../shared.ts";
-
-/**
- * Source-to-source rewrites that turn Nextra-only MDX into idiomatic Blume
- * markup. Runs once at migration time.
- */
-
-/** Nextra `<Callout type="X">` values mapped to Blume directive names. */
-const CALLOUT_TYPE_DIRECTIVES: Record<string, string> = {
-  default: "note",
-  error: "danger",
-  info: "info",
-  warning: "warning",
-};
-
-/**
- * Convert Nextra `<Callout>` components (with an optional `type`) into Blume
- * `:::` directives. A bare `<Callout>` becomes `:::note`; the `emoji` prop is
- * dropped.
- */
-export const rewriteNextraCallouts = (source: string): string =>
-  rewriteCallouts(source, {
-    defaultDirective: "note",
-    tagDirectives: {},
-    tags: ["Callout"],
-    typeDirectives: CALLOUT_TYPE_DIRECTIVES,
-  });
-
-const NEXTRA_IMPORT =
-  /^import\s+[\s\S]*?\s+from\s+["']nextra(?:\/[^"']*)?["'];?[ \t]*\n?/gmu;
-
-/**
- * Drop `import … from "nextra/…"` statements. Blume injects its components
- * globally, so these imports would fail to resolve once `nextra` is gone.
- */
-export const stripNextraImports = (source: string): string =>
-  source.replace(NEXTRA_IMPORT, "");
-
-/** Nextra components with no drop-in Blume equivalent — flagged for review. */
-const UNSUPPORTED_COMPONENTS = ["Bleed", "Cards", "FileTree", "Steps", "Tabs"];
-
-/** Names of Nextra components in `source` that need manual attention. */
-export const unsupportedNextraComponents = (source: string): string[] =>
-  UNSUPPORTED_COMPONENTS.filter((name) =>
-    new RegExp(`<${name}\\b`, "u").test(source)
-  );

package/src/migrate/nextra/frontmatter.ts

@@ -1,40 +0,0 @@
-import { stripUnknownPageMeta } from "../shared.ts";
-
-export interface NextraPageOverride {
-  hidden?: boolean;
-  label?: string;
-}
-
-/**
- * Fold Nextra `_meta` overrides (a sidebar label, `display: "hidden"`) into a
- * page's frontmatter, then drop any keys Blume's strict page schema rejects.
- * Nextra's own `title`/`description`/`sidebarTitle` already validate and pass
- * through untouched. Explicit page frontmatter wins over `_meta` overrides.
- */
-export const normalizeNextraPageMeta = (
-  value: unknown,
-  override: NextraPageOverride = {}
-): { data: Record<string, unknown>; removed: string[] } => {
-  const source =
-    value && typeof value === "object"
-      ? (value as Record<string, unknown>)
-      : {};
-  const data: Record<string, unknown> = { ...source };
-
-  const sidebar: Record<string, unknown> = {
-    ...(typeof source.sidebar === "object" && source.sidebar !== null
-      ? (source.sidebar as Record<string, unknown>)
-      : {}),
-  };
-  if (override.label !== undefined && sidebar.label === undefined) {
-    sidebar.label = override.label;
-  }
-  if (override.hidden && sidebar.hidden === undefined) {
-    sidebar.hidden = true;
-  }
-  if (Object.keys(sidebar).length > 0) {
-    data.sidebar = sidebar;
-  }
-
-  return stripUnknownPageMeta(data);
-};

package/src/migrate/nextra/index.ts

@@ -1,374 +0,0 @@
-import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-
-import { basename, dirname, extname, join, relative } from "pathe";
-import { glob } from "tinyglobby";
-
-import matter from "../../core/frontmatter.ts";
-import type { BlumeConfig, FolderMeta } from "../../core/schema.ts";
-import { writeBlumeConfig } from "../shared.ts";
-import {
-  rewriteNextraCallouts,
-  stripNextraImports,
-  unsupportedNextraComponents,
-} from "./content.ts";
-import type { NextraPageOverride } from "./frontmatter.ts";
-import { normalizeNextraPageMeta } from "./frontmatter.ts";
-import { parseNextraMeta, toBlumeFolderMeta } from "./meta.ts";
-
-export interface NextraMigrationResult {
-  moved: number;
-  warnings: string[];
-}
-
-interface Tab {
-  label: string;
-  path: string;
-}
-
-interface FolderIndex {
-  childDirs: Map<string, Set<string>>;
-  pagesByDir: Map<string, Map<string, string>>;
-}
-
-interface MetaPlan {
-  consumedMetas: string[];
-  folderTitleByDir: Map<string, string>;
-  metaByDir: Map<string, FolderMeta>;
-  pageOverrides: Map<string, NextraPageOverride>;
-  tabs: Tab[];
-  unparseableMetas: { abs: string; rel: string }[];
-  warnings: string[];
-}
-
-interface PageMove {
-  moved: number;
-  removed: string[];
-  skipped: string | null;
-  unsupported: string[];
-}
-
-/** Nextra keeps docs under `content/` (App Router) or `pages/` (Pages Router). */
-const SOURCE_DIRS = ["content", "pages"];
-
-const PAGE_GLOB = "**/*.{md,mdx}";
-const META_GLOB = "**/_meta.{js,mjs,cjs,ts,jsx,tsx,json}";
-const IGNORE = ["**/node_modules/**"];
-
-/** Normalize a `dirname` result so the content root is "" rather than ".". */
-const normalizeDir = (dir: string): string => (dir === "." ? "" : dir);
-
-const mergeOverride = (
-  map: Map<string, NextraPageOverride>,
-  key: string,
-  patch: NextraPageOverride
-): void => {
-  map.set(key, { ...map.get(key), ...patch });
-};
-
-/** Index which child slugs in each folder are pages vs subdirectories. */
-const indexFolders = (
-  base: string,
-  pageFiles: string[],
-  metaFiles: string[]
-): FolderIndex => {
-  const pagesByDir = new Map<string, Map<string, string>>();
-  const allDirs = new Set<string>([""]);
-  const registerDir = (dir: string): void => {
-    let current = normalizeDir(dir);
-    allDirs.add(current);
-    while (current !== "") {
-      current = normalizeDir(dirname(current));
-      allDirs.add(current);
-    }
-  };
-
-  for (const abs of pageFiles) {
-    const rel = relative(base, abs);
-    const dir = normalizeDir(dirname(rel));
-    const slug = basename(rel).replace(/\.mdx?$/u, "");
-    const folder = pagesByDir.get(dir) ?? new Map<string, string>();
-    folder.set(slug, abs);
-    pagesByDir.set(dir, folder);
-    registerDir(dir);
-  }
-  for (const abs of metaFiles) {
-    registerDir(normalizeDir(dirname(relative(base, abs))));
-  }
-
-  const childDirs = new Map<string, Set<string>>();
-  for (const dir of allDirs) {
-    if (dir === "") {
-      continue;
-    }
-    const parent = normalizeDir(dirname(dir));
-    const children = childDirs.get(parent) ?? new Set<string>();
-    children.add(basename(dir));
-    childDirs.set(parent, children);
-  }
-
-  return { childDirs, pagesByDir };
-};
-
-interface ParsedMeta {
-  abs: string;
-  ext: string;
-  raw: string;
-  rel: string;
-}
-
-/** Parse every `_meta`, accumulating ordering, titles, and page overrides. */
-const planMetas = (metas: ParsedMeta[], index: FolderIndex): MetaPlan => {
-  const plan: MetaPlan = {
-    consumedMetas: [],
-    folderTitleByDir: new Map(),
-    metaByDir: new Map(),
-    pageOverrides: new Map(),
-    tabs: [],
-    unparseableMetas: [],
-    warnings: [],
-  };
-
-  for (const meta of metas) {
-    const dir = normalizeDir(dirname(meta.rel));
-    const entries = parseNextraMeta(meta.raw, meta.ext);
-    if (!entries) {
-      plan.unparseableMetas.push({ abs: meta.abs, rel: meta.rel });
-      continue;
-    }
-
-    const conversion = toBlumeFolderMeta(entries, {
-      hasDir: (slug) => index.childDirs.get(dir)?.has(slug) ?? false,
-      hasPage: (slug) => index.pagesByDir.get(dir)?.has(slug) ?? false,
-    });
-
-    plan.metaByDir.set(dir, conversion.folderMeta);
-    plan.consumedMetas.push(meta.abs);
-    for (const [slug, title] of Object.entries(conversion.folderTitles)) {
-      plan.folderTitleByDir.set(normalizeDir(join(dir, slug)), title);
-    }
-    for (const [slug, label] of Object.entries(conversion.pageLabels)) {
-      const pageAbs = index.pagesByDir.get(dir)?.get(slug);
-      if (pageAbs) {
-        mergeOverride(plan.pageOverrides, pageAbs, { label });
-      }
-    }
-    for (const slug of conversion.hiddenPages) {
-      const pageAbs = index.pagesByDir.get(dir)?.get(slug);
-      if (pageAbs) {
-        mergeOverride(plan.pageOverrides, pageAbs, { hidden: true });
-      }
-    }
-    if (dir === "") {
-      plan.tabs.push(...conversion.navPages);
-    } else if (conversion.navPages.length > 0) {
-      plan.warnings.push(
-        `Ignored ${conversion.navPages.length} top-nav page entr(y/ies) in ${meta.rel}; type:"page" only maps at the root.`
-      );
-    }
-    plan.warnings.push(...conversion.warnings);
-  }
-
-  return plan;
-};
-
-/** Move and rewrite a single page into `docs/`. */
-const movePage = async (
-  abs: string,
-  options: {
-    base: string;
-    overrides: Map<string, NextraPageOverride>;
-    root: string;
-  }
-): Promise<PageMove> => {
-  const rel = relative(options.base, abs);
-  const dest = join(options.root, "docs", rel);
-  if (existsSync(dest)) {
-    return { moved: 0, removed: [], skipped: rel, unsupported: [] };
-  }
-  const raw = await readFile(abs, "utf-8");
-  const text = rewriteNextraCallouts(stripNextraImports(raw));
-  const unsupported = unsupportedNextraComponents(text);
-  const parsed = matter(text);
-  const { data, removed } = normalizeNextraPageMeta(
-    parsed.data,
-    options.overrides.get(abs) ?? {}
-  );
-  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 { moved: 1, removed, skipped: null, unsupported };
-};
-
-interface PageSummary {
-  moved: number;
-  removedKeys: string[];
-  skipped: string[];
-  unsupported: string[];
-}
-
-const summarizePageMoves = (results: PageMove[]): PageSummary => {
-  let moved = 0;
-  const removedKeys = new Set<string>();
-  const unsupported = new Set<string>();
-  const skipped: string[] = [];
-  for (const result of results) {
-    moved += result.moved;
-    if (result.skipped) {
-      skipped.push(result.skipped);
-    }
-    for (const key of result.removed) {
-      removedKeys.add(key);
-    }
-    for (const name of result.unsupported) {
-      unsupported.add(name);
-    }
-  }
-  return {
-    moved,
-    removedKeys: [...removedKeys],
-    skipped,
-    unsupported: [...unsupported],
-  };
-};
-
-/** Write a `meta.ts` per folder, merging own ordering with a parent title. */
-const writeFolderMetas = async (
-  root: string,
-  plan: MetaPlan
-): Promise<void> => {
-  const dirs = new Set<string>([
-    ...plan.metaByDir.keys(),
-    ...plan.folderTitleByDir.keys(),
-  ]);
-  await Promise.all(
-    [...dirs].map(async (dir) => {
-      const finalMeta: FolderMeta = { ...plan.metaByDir.get(dir) };
-      const title = plan.folderTitleByDir.get(dir);
-      if (title !== undefined) {
-        finalMeta.title = title;
-      }
-      if (Object.keys(finalMeta).length === 0) {
-        return;
-      }
-      const dest = join(root, "docs", dir, "meta.ts");
-      await mkdir(dirname(dest), { recursive: true });
-      await writeFile(
-        dest,
-        `import { defineMeta } from "blume";\n\nexport default defineMeta(${JSON.stringify(finalMeta, null, 2)});\n`,
-        "utf-8"
-      );
-    })
-  );
-};
-
-/** Relocate `_meta` files we couldn't parse, untouched, for manual conversion. */
-const relocateUnparseableMetas = async (
-  root: string,
-  metas: { abs: string; rel: string }[]
-): Promise<string[]> => {
-  const warnings: string[] = [];
-  await Promise.all(
-    metas.map(async ({ abs, rel }) => {
-      const dest = join(root, "docs", rel);
-      if (existsSync(dest)) {
-        warnings.push(`Skipped ${rel} (target already exists)`);
-        return;
-      }
-      await mkdir(dirname(dest), { recursive: true });
-      await rename(abs, dest);
-      warnings.push(
-        `Could not parse ${rel}; moved as-is — convert it to meta.ts by hand.`
-      );
-    })
-  );
-  return warnings;
-};
-
-const buildConfig = (tabs: Tab[]): BlumeConfig =>
-  tabs.length > 0
-    ? { navigation: { tabs }, title: "Documentation" }
-    : { title: "Documentation" };
-
-/**
- * Migrate a Nextra project to Blume: move every `.md`/`.mdx` page into `docs/`,
- * rewrite Nextra `<Callout>`s to directives, and convert each `_meta` file into
- * a typed `meta.ts`. Nextra declares a folder's title (and per-page sidebar
- * labels) in the *parent* `_meta`, so those are propagated into child `meta.ts`
- * titles and page frontmatter. Content lands in the default `docs/` root.
- */
-export const migrateNextraProject = async (
-  root: string
-): Promise<NextraMigrationResult> => {
-  const sourceDir = SOURCE_DIRS.find((dir) => existsSync(join(root, dir)));
-  if (!sourceDir) {
-    await writeBlumeConfig(root, { title: "Documentation" });
-    return {
-      moved: 0,
-      warnings: [
-        "No Nextra content directory (content/ or pages/) found; wrote a default config.",
-      ],
-    };
-  }
-  const base = join(root, sourceDir);
-
-  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 index = indexFolders(base, pageFiles, metaFiles);
-  const metas = await Promise.all(
-    metaFiles.map(async (abs) => ({
-      abs,
-      ext: extname(abs),
-      raw: await readFile(abs, "utf-8"),
-      rel: relative(base, abs),
-    }))
-  );
-  const plan = planMetas(metas, index);
-
-  const moves = await Promise.all(
-    pageFiles.map((abs) =>
-      movePage(abs, { base, overrides: plan.pageOverrides, root })
-    )
-  );
-  const pages = summarizePageMoves(moves);
-
-  await writeFolderMetas(root, plan);
-  await Promise.all(plan.consumedMetas.map((abs) => rm(abs, { force: true })));
-  const relocateWarnings = await relocateUnparseableMetas(
-    root,
-    plan.unparseableMetas
-  );
-  await writeBlumeConfig(root, buildConfig(plan.tabs));
-
-  const warnings = [
-    ...plan.warnings,
-    ...pages.skipped.map((rel) => `Skipped ${rel} (target already exists)`),
-    ...relocateWarnings,
-  ];
-  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 };
-};