blume 0.0.0 → 0.1.0

package/src/migrate/mintlify/content.ts

@@ -0,0 +1,98 @@
+import { dirname, join, relative } from "pathe";
+
+import { rewriteCallouts } from "../shared.ts";
+
+/**
+ * Source-to-source rewrites that turn Mintlify-only MDX component syntax into
+ * idiomatic Blume markup. Runs once at migration time — no Mintlify-aware
+ * plugins remain in the Blume runtime.
+ */
+
+/** Mintlify callout components mapped to Blume directive names. */
+const CALLOUT_DIRECTIVES: Record<string, string> = {
+  Check: "success",
+  Danger: "danger",
+  Error: "danger",
+  Info: "info",
+  Note: "note",
+  Success: "success",
+  Tip: "tip",
+  Warning: "warning",
+};
+
+/** `<Callout type="X">` values mapped to Blume directive names. */
+const CALLOUT_TYPE_DIRECTIVES: Record<string, string> = {
+  caution: "warning",
+  check: "success",
+  danger: "danger",
+  error: "danger",
+  info: "info",
+  note: "note",
+  success: "success",
+  tip: "tip",
+  warning: "warning",
+};
+
+/**
+ * Convert Mintlify callout components (`<Note>`, `<Warning>`, `<Callout
+ * type="…">`, …) into Blume `:::` directives.
+ */
+export const rewriteMintlifyCallouts = (source: string): string =>
+  rewriteCallouts(source, {
+    defaultDirective: "note",
+    tagDirectives: CALLOUT_DIRECTIVES,
+    tags: ["Callout", ...Object.keys(CALLOUT_DIRECTIVES)],
+    typeDirectives: CALLOUT_TYPE_DIRECTIVES,
+  });
+
+/**
+ * Mintlify's `<RequestExample>`/`<ResponseExample>` are tab-style code wrappers
+ * with no Blume equivalent; rename them to `<CodeGroup>`, which renders the
+ * same titled-fence tabs.
+ */
+export const rewriteMintlifyExampleBlocks = (source: string): string =>
+  source.replaceAll(
+    /<(?<close>\/?)(?:Request|Response)Example\b/gu,
+    "<$<close>CodeGroup"
+  );
+
+const SNIPPET_IMPORT =
+  /^import\s+[\s\S]*?\s+from\s+["'](?<source>\/snippets\/[^"']+)["'];?[ \t]*\n?/gmu;
+
+/**
+ * After snippets are inlined, clean up leftover `/snippets/*` imports: drop the
+ * now-dead markdown imports, and rewrite component imports (`.jsx`/`.tsx`/…) to
+ * a path relative to the page so they still resolve once `/snippets` content is
+ * gone. Returns the rewritten source and the component files still referenced.
+ */
+export const rewriteSnippetImports = (
+  source: string,
+  options: { filePath: string; root: string }
+): { components: string[]; source: string } => {
+  const components: string[] = [];
+  const next = source.replaceAll(
+    SNIPPET_IMPORT,
+    (match, importSource: string) => {
+      if (/\.mdx?$/u.test(importSource)) {
+        return "";
+      }
+      const target = join(options.root, importSource.replace(/^\/+/u, ""));
+      components.push(importSource.replace(/^\/+/u, ""));
+      let rel = relative(dirname(options.filePath), target);
+      if (!rel.startsWith(".")) {
+        rel = `./${rel}`;
+      }
+      return match.replace(importSource, rel);
+    }
+  );
+  return { components, source: next };
+};
+
+/** Component tags Blume has no equivalent for — reported for manual review. */
+const UNSUPPORTED_COMPONENTS = ["ParamField", "ResponseField"];
+
+/** Names of Mintlify components in `source` that need manual attention. */
+export const unsupportedMintlifyComponents = (source: string): string[] =>
+  UNSUPPORTED_COMPONENTS.filter((name) =>
+    new RegExp(`<${name}\\b`, "u").test(source)
+  );

package/src/migrate/mintlify/frontmatter.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+
+/**
+ * One-time translation of Mintlify page frontmatter into Blume's shape. This
+ * runs at migration time only — Blume's runtime page schema stays
+ * Mintlify-free and strict. `sidebarTitle`/`icon`/`tag`/`hidden` fold into
+ * `sidebar`, `hidden` implies `noindex`, `canonical`/`og:image` move under
+ * `seo`, and OpenAPI/AsyncAPI pages become `type: "api"`.
+ */
+
+const mintlifySidebarMetaSchema = z
+  .object({
+    badge: z.string().optional(),
+    hidden: z.boolean().optional(),
+    icon: z.string().optional(),
+    label: z.string().optional(),
+    order: z.number().optional(),
+  })
+  .passthrough();
+
+const mintlifyPageMetaInputSchema = z
+  .object({
+    api: z.unknown().optional(),
+    asyncapi: z.string().optional(),
+    canonical: z.string().optional(),
+    hidden: z.boolean().optional(),
+    icon: z.string().optional(),
+    noindex: z.boolean().optional(),
+    "og:image": z.string().optional(),
+    openapi: z.string().optional(),
+    sidebar: mintlifySidebarMetaSchema.optional(),
+    sidebarTitle: z.string().optional(),
+    tag: z.string().optional(),
+    type: z.string().optional(),
+  })
+  .passthrough();
+
+type MintlifyPageMetaInput = z.infer<typeof mintlifyPageMetaInputSchema>;
+
+const normalizedMintlifySidebar = (meta: MintlifyPageMetaInput) => ({
+  ...meta.sidebar,
+  ...(meta.sidebarTitle !== undefined && meta.sidebar?.label === undefined
+    ? { label: meta.sidebarTitle }
+    : {}),
+  ...(meta.icon !== undefined && meta.sidebar?.icon === undefined
+    ? { icon: meta.icon }
+    : {}),
+  ...(meta.tag !== undefined && meta.sidebar?.badge === undefined
+    ? { badge: meta.tag }
+    : {}),
+  ...(meta.hidden === true && meta.sidebar?.hidden === undefined
+    ? { hidden: true }
+    : {}),
+});
+
+const mintlifyPageType = (meta: MintlifyPageMetaInput): string | undefined =>
+  meta.type ??
+  (meta.openapi !== undefined ||
+  meta.asyncapi !== undefined ||
+  meta.api !== undefined
+    ? "api"
+    : undefined);
+
+const mintlifyNoindex = (meta: MintlifyPageMetaInput): boolean | undefined =>
+  meta.hidden === true && meta.noindex === undefined ? true : meta.noindex;
+
+/** Top-level Mintlify keys folded elsewhere — removed from the output. */
+const CONSUMED_KEYS = new Set([
+  "canonical",
+  "hidden",
+  "icon",
+  "og:image",
+  "sidebarTitle",
+  "tag",
+]);
+
+/** Map Mintlify page frontmatter onto Blume's frontmatter shape. */
+export const normalizeMintlifyPageMeta = (
+  value: unknown
+): Record<string, unknown> => {
+  const parsed = mintlifyPageMetaInputSchema.safeParse(value);
+  if (!parsed.success || typeof value !== "object" || value === null) {
+    return (value ?? {}) as Record<string, unknown>;
+  }
+
+  const meta = parsed.data;
+  const source = value as Record<string, unknown>;
+  const data: Record<string, unknown> = { ...source };
+
+  const sidebar = normalizedMintlifySidebar(meta);
+  if (Object.keys(sidebar).length > 0) {
+    data.sidebar = sidebar;
+  }
+
+  const seo: Record<string, unknown> = {
+    ...(typeof source.seo === "object" && source.seo !== null
+      ? (source.seo as Record<string, unknown>)
+      : {}),
+  };
+  if (meta.canonical !== undefined && seo.canonical === undefined) {
+    seo.canonical = meta.canonical;
+  }
+  if (meta["og:image"] !== undefined && seo.image === undefined) {
+    seo.image = meta["og:image"];
+  }
+  if (Object.keys(seo).length > 0) {
+    data.seo = seo;
+  }
+
+  const noindex = mintlifyNoindex(meta);
+  if (noindex !== undefined) {
+    data.noindex = noindex;
+  }
+  const type = mintlifyPageType(meta);
+  if (type !== undefined) {
+    data.type = type;
+  }
+
+  const cleaned: Record<string, unknown> = {};
+  for (const [key, raw] of Object.entries(data)) {
+    if (!CONSUMED_KEYS.has(key)) {
+      cleaned[key] = raw;
+    }
+  }
+  return cleaned;
+};

package/src/migrate/mintlify/i18n.ts

@@ -0,0 +1,51 @@
+import type { BlumeConfig } from "../../core/schema.ts";
+
+/** A Mintlify `navigation.languages[]` entry. */
+interface MintlifyLanguage {
+  language: string;
+  default?: boolean;
+}
+
+/**
+ * A display label for a locale code — the language's native name when the
+ * runtime knows it (`fr` -> `Français`), else the code itself.
+ */
+const localeLabel = (code: string): string => {
+  try {
+    const native = new Intl.DisplayNames([code], { type: "language" }).of(code);
+    if (native && native !== code) {
+      return native.charAt(0).toUpperCase() + native.slice(1);
+    }
+  } catch {
+    // Unknown code or no ICU data; fall through to the code.
+  }
+  return code;
+};
+
+/**
+ * Map a Mintlify `navigation.languages[]` array to a Blume `i18n` config. The
+ * entry marked `default: true` becomes `defaultLocale`; translated content
+ * already lives in ISO-code directories, which match Blume's `dir` parser.
+ */
+export const mintlifyI18n = (
+  spec: Record<string, unknown>
+): BlumeConfig["i18n"] | null => {
+  const navigation = spec.navigation as
+    | { languages?: MintlifyLanguage[] }
+    | undefined;
+  const languages = navigation?.languages;
+  if (!Array.isArray(languages) || languages.length < 2) {
+    return null;
+  }
+  const defaultLocale =
+    languages.find((entry) => entry.default)?.language ??
+    languages[0]?.language ??
+    "en";
+  return {
+    defaultLocale,
+    locales: languages.map((entry) => ({
+      code: entry.language,
+      label: localeLabel(entry.language),
+    })),
+  };
+};

package/src/migrate/mintlify/icons.ts

@@ -0,0 +1,128 @@
+const JSX_ATTRIBUTE_ALIASES: Record<string, string> = {
+  className: "class",
+  clipPath: "clip-path",
+  clipRule: "clip-rule",
+  fillOpacity: "fill-opacity",
+  fillRule: "fill-rule",
+  strokeDasharray: "stroke-dasharray",
+  strokeDashoffset: "stroke-dashoffset",
+  strokeLinecap: "stroke-linecap",
+  strokeLinejoin: "stroke-linejoin",
+  strokeMiterlimit: "stroke-miterlimit",
+  strokeOpacity: "stroke-opacity",
+  strokeWidth: "stroke-width",
+};
+
+const SVG_EXPRESSION = /^\s*\(?\s*<svg[\s\S]*<\/svg>\s*\)?\s*;?\s*$/u;
+
+const escapeAttribute = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+const stripExpressionWrapper = (value: string): string => {
+  let next = value.trim().replaceAll(/;$/gu, "").trim();
+  if (next.startsWith("(") && next.endsWith(")")) {
+    next = next.slice(1, -1).trim();
+  }
+  return next;
+};
+
+const jsxExpressionAttribute = (
+  value: string,
+  quoted: string | undefined,
+  single: string | undefined,
+  template: string | undefined,
+  scalar: string | undefined
+): string => {
+  const literal = quoted ?? single ?? template ?? scalar;
+  return literal === undefined ? value : `="${escapeAttribute(literal)}"`;
+};
+
+const normalizeJsxSvg = (value: string): string | null => {
+  const stripped = stripExpressionWrapper(value);
+  if (!SVG_EXPRESSION.test(stripped)) {
+    return null;
+  }
+
+  let svg = stripped.replaceAll(
+    /[=]\{\s*(?:"(?<quoted>[^"]*)"|'(?<single>[^']*)'|`(?<template>[^`]*)`|(?<scalar>-?\d+(?:\.\d+)?|true|false))\s*\}/gu,
+    jsxExpressionAttribute
+  );
+  for (const [jsxName, htmlName] of Object.entries(JSX_ATTRIBUTE_ALIASES)) {
+    svg = svg.replaceAll(new RegExp(`\\b${jsxName}=`, "gu"), `${htmlName}=`);
+  }
+  return svg;
+};
+
+const findExpressionEnd = (source: string, start: number): number => {
+  let depth = 1;
+  let quote: '"' | "'" | "`" | null = null;
+  for (let index = start; index < source.length; index += 1) {
+    const char = source[index];
+    const previous = source[index - 1];
+    if (quote) {
+      if (char === quote && previous !== "\\") {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
+};
+
+const startsWithSvgExpression = (value: string): boolean => {
+  const trimmed = value.trimStart();
+  return trimmed.startsWith("<svg") || trimmed.startsWith("(<svg");
+};
+
+/**
+ * Rewrite Mintlify inline-SVG icon JSX props (`icon={<svg .../>}`) to plain
+ * string props so the migrated MDX compiles under Astro. Runs once at
+ * migration time; non-SVG `icon={...}` expressions are left untouched.
+ */
+export const rewriteMintlifySvgIconProps = (source: string): string => {
+  let output = "";
+  let cursor = 0;
+  while (cursor < source.length) {
+    const start = source.indexOf("icon={", cursor);
+    if (start === -1) {
+      output += source.slice(cursor);
+      break;
+    }
+
+    const expressionStart = start + "icon={".length;
+    const end = findExpressionEnd(source, expressionStart);
+    if (end === -1) {
+      output += source.slice(cursor);
+      break;
+    }
+
+    const expression = source.slice(expressionStart, end);
+    const svg = startsWithSvgExpression(expression)
+      ? normalizeJsxSvg(expression)
+      : null;
+    output += source.slice(cursor, start);
+    output += svg
+      ? `icon={${JSON.stringify(svg)}}`
+      : source.slice(start, end + 1);
+    cursor = end + 1;
+  }
+  return output;
+};

package/src/migrate/mintlify/index.ts

@@ -0,0 +1,266 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+
+import { dirname, join } from "pathe";
+import { glob } from "tinyglobby";
+
+import type { BlumeConfig } from "../../core/schema.ts";
+import { loadMintlifyConfig } from "./config.ts";
+import { mintlifyI18n } from "./i18n.ts";
+import { transformMintlifyContent } from "./transform.ts";
+
+export interface MintlifyMigrationResult {
+  moved: number;
+  warnings: string[];
+}
+
+/** Recursively drop `undefined`, empty arrays, and empty objects. */
+const prune = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(prune);
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, raw] of Object.entries(value)) {
+      const pruned = prune(raw);
+      if (pruned === undefined) {
+        continue;
+      }
+      if (Array.isArray(pruned) && pruned.length === 0) {
+        continue;
+      }
+      if (
+        pruned &&
+        typeof pruned === "object" &&
+        !Array.isArray(pruned) &&
+        Object.keys(pruned).length === 0
+      ) {
+        continue;
+      }
+      out[key] = pruned;
+    }
+    return out;
+  }
+  return value;
+};
+
+const writeBlumeConfig = async (
+  root: string,
+  config: BlumeConfig
+): Promise<void> => {
+  const body = `import { defineConfig } from "blume";\n\nexport default defineConfig(${JSON.stringify(prune(config), null, 2)});\n`;
+  await writeFile(join(root, "blume.config.ts"), body, "utf-8");
+};
+
+/** Move a referenced top-level asset path (file or dir) under `public/`. */
+const relocateAssets = async (
+  root: string,
+  refs: unknown[]
+): Promise<string[]> => {
+  const segments = new Set<string>();
+  for (const ref of refs) {
+    if (typeof ref !== "string" || !ref.startsWith("/")) {
+      continue;
+    }
+    const [segment] = ref.replace(/^\/+/u, "").split("/");
+    if (segment) {
+      segments.add(segment);
+    }
+  }
+
+  const moved: string[] = [];
+  for (const segment of segments) {
+    const source = join(root, segment);
+    if (!existsSync(source) || segment === "public") {
+      continue;
+    }
+    const dest = join(root, "public", segment);
+    if (existsSync(dest)) {
+      continue;
+    }
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs moves
+    await mkdir(join(root, "public"), { recursive: true });
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs moves
+    await rename(source, dest);
+    moved.push(segment);
+  }
+  return moved;
+};
+
+/**
+ * Delete the inlined markdown snippets. Component files (e.g. `.jsx`) are kept
+ * because their imports were rewritten to resolve against `/snippets`.
+ */
+const cleanupSnippets = async (
+  root: string,
+  kept: Set<string>,
+  warnings: string[]
+): Promise<void> => {
+  const dir = join(root, "snippets");
+  if (!existsSync(dir)) {
+    return;
+  }
+  const markdown = await glob(["**/*.{md,mdx}"], { absolute: true, cwd: dir });
+  for (const file of markdown) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs removes
+    await rm(file, { force: true });
+  }
+  const remaining = await glob(["**/*"], { cwd: dir, dot: true });
+  if (remaining.length === 0) {
+    await rm(dir, { force: true, recursive: true });
+    warnings.push("Inlined and removed the /snippets directory.");
+  } else {
+    warnings.push(
+      `Inlined markdown snippets; kept ${remaining.length} component file(s) under /snippets.`
+    );
+  }
+  if (kept.size > 0) {
+    warnings.push(
+      `Rewrote ${kept.size} component snippet import(s) to relative paths; verify they resolve.`
+    );
+  }
+};
+
+/** 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;
+};
+
+/**
+ * Migrate a Mintlify project to Blume: translate `docs.json`/`mint.json` into
+ * `blume.config.ts`, rewrite every page to idiomatic Blume MDX in place, and
+ * relocate static assets. Content stays at the project root (`content.root`
+ * is `"."`).
+ */
+export const migrateMintlifyProject = async (
+  root: string
+): Promise<MintlifyMigrationResult> => {
+  const warnings: string[] = [];
+  const configFile = existsSync(join(root, "docs.json"))
+    ? join(root, "docs.json")
+    : join(root, "mint.json");
+
+  let config: BlumeConfig;
+  if (existsSync(configFile)) {
+    config = await loadMintlifyConfig(root, configFile);
+    const spec = JSON.parse(await readFile(configFile, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+    const i18n = mintlifyI18n(spec);
+    if (i18n) {
+      config.i18n = i18n;
+      // Language switching is handled by Blume i18n, not a nav selector.
+      if (config.navigation?.selectors) {
+        config.navigation.selectors = config.navigation.selectors.filter(
+          (selector) => selector.kind !== "language"
+        );
+      }
+      warnings.push(
+        `Mapped ${i18n.locales.length} languages to i18n.locales (default: ${i18n.defaultLocale}); review the locale labels.`
+      );
+    }
+  } else {
+    warnings.push("No docs.json or mint.json found; writing a default config.");
+    config = { content: { root: "." }, title: "Documentation" };
+  }
+
+  const variables = (config.variables as Record<string, string>) ?? {};
+  // Globals are inlined into content below; Blume has no runtime substitution.
+  config.variables = undefined;
+
+  const files = await glob(["**/*.{md,mdx}"], {
+    absolute: true,
+    cwd: root,
+    ignore: [
+      "node_modules/**",
+      ".blume/**",
+      "dist/**",
+      "public/**",
+      "snippets/**",
+    ],
+  });
+
+  let moved = 0;
+  const removedKeys = new Set<string>();
+  const unsupported = new Set<string>();
+  const keptComponents = new Set<string>();
+  for (const file of files) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
+    const raw = await readFile(file, "utf-8");
+    // oxlint-disable-next-line no-await-in-loop -- sequential transforms
+    const result = await transformMintlifyContent(raw, {
+      filePath: file,
+      root,
+      variables,
+    });
+    if (result.content !== raw) {
+      // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
+      await mkdir(dirname(file), { recursive: true });
+      // oxlint-disable-next-line no-await-in-loop -- sequential fs writes
+      await writeFile(file, result.content, "utf-8");
+    }
+    for (const key of result.removed) {
+      removedKeys.add(key);
+    }
+    for (const name of result.unsupported) {
+      unsupported.add(name);
+    }
+    for (const name of result.components) {
+      keptComponents.add(name);
+    }
+    moved += 1;
+  }
+
+  const movedAssets = await relocateAssets(root, assetRefs(config));
+  await cleanupSnippets(root, keptComponents, warnings);
+
+  if (config.content?.exclude) {
+    config.content.exclude = [...new Set(config.content.exclude)];
+  }
+  await writeBlumeConfig(root, config);
+
+  if (Object.keys(variables).length > 0) {
+    warnings.push(
+      `Inlined ${Object.keys(variables).length} docs.json variable(s) into content; Blume has no runtime variable substitution.`
+    );
+  }
+  if (movedAssets.length > 0) {
+    warnings.push(`Moved assets into public/: ${movedAssets.join(", ")}.`);
+  }
+  if (removedKeys.size > 0) {
+    warnings.push(
+      `Dropped unsupported page frontmatter keys: ${[...removedKeys].join(", ")}.`
+    );
+  }
+  if (unsupported.size > 0) {
+    warnings.push(
+      `Components without a Blume equivalent need manual review (use the OpenAPI reference instead): ${[...unsupported].join(", ")}.`
+    );
+  }
+  warnings.push(
+    "Review blume.config.ts; navigation, theme, and chrome were mapped from docs.json."
+  );
+
+  return { moved, warnings };
+};