blume 0.5.3 → 0.6.0

package/src/migrate/mintlify/snippets.ts

@@ -1,315 +0,0 @@
-import { readFile as readFileFromDisk } from "node:fs/promises";
-
-import { dirname, relative, resolve } from "pathe";
-
-import matter from "../../core/frontmatter.ts";
-import { isInsideRoot, stripImports } from "../shared.ts";
-
-const MARKDOWN_SNIPPET_IMPORT =
-  /^import\s+(?<name>[$A-Z_a-z][$\w]*)\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
-const NAMED_SNIPPET_IMPORT =
-  /^import\s+\{(?<names>[^}]+)\}\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
-const EXPORTED_STRING_CONST =
-  /^export\s+const\s+(?<name>[$A-Z_a-z][$\w]*)\s*=\s*(?:"(?<double>(?:\\.|[^"\\])*)"|'(?<single>(?:\\.|[^'\\])*)'|`(?<template>(?:\\.|[^`\\])*)`)\s*;?\s*$/gmu;
-const ATTRIBUTE =
-  /\s+(?<name>[$A-Z_a-z][$\w:-]*)(?:=(?:"(?<quoted>[^"]*)"|'(?<single>[^']*)'|\{(?<expression>[^}]*)\}))?/gu;
-const PLACEHOLDER = /\{(?<name>[$A-Z_a-z][$\w]*)\}/gu;
-const GLOBAL_VARIABLE = /\{\{\s*(?<name>[A-Za-z0-9-]+)\s*\}\}/gu;
-const FRONTMATTER_BLOCK = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/u;
-const USER_EXPORT =
-  /^(?:export\s+)?(?:const|let|var)\s+user\s*=|^import\s+\{\s*user\s*\}/mu;
-
-interface SnippetImport {
-  importText: string;
-  name: string;
-  source: string;
-}
-
-interface SnippetVariableImport {
-  names: { imported: string; local: string }[];
-  source: string;
-}
-
-interface SnippetTransformOptions {
-  filePath: string;
-  root: string;
-  readFile?: (file: string) => Promise<string>;
-  seen?: Set<string>;
-  trail?: string[];
-}
-
-const escapeRegExp = (value: string): string =>
-  value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-
-const snippetSelfClosingTagPattern = (name: string): RegExp =>
-  new RegExp(`<${escapeRegExp(name)}(?<attrs>[^>]*?)\\s*/>`, "gu");
-
-const snippetPairedTagPattern = (name: string): RegExp =>
-  new RegExp(
-    `<${escapeRegExp(name)}(?<attrs>[^>]*?)>[\\s\\S]*?</${escapeRegExp(name)}>`,
-    "gu"
-  );
-
-const rootRelativePath = (root: string, file: string): string => {
-  const rel = relative(root, file);
-  return rel ? `/${rel}` : "/";
-};
-
-const snippetCycleMessage = (
-  root: string,
-  file: string,
-  trail: string[]
-): string => {
-  const cycleStart = trail.indexOf(file);
-  const cycle = [...(cycleStart === -1 ? trail : trail.slice(cycleStart)), file]
-    .map((entry) => rootRelativePath(root, entry))
-    .join(" -> ");
-  return `Circular Mintlify snippet import detected: ${cycle}`;
-};
-
-const resolveSnippetPath = (options: {
-  filePath: string;
-  root: string;
-  source: string;
-}): string | null => {
-  const target = options.source.startsWith("/")
-    ? resolve(options.root, options.source.slice(1))
-    : resolve(dirname(options.filePath), options.source);
-  return isInsideRoot(options.root, target) ? target : null;
-};
-
-const collectImports = (source: string): SnippetImport[] =>
-  [...source.matchAll(MARKDOWN_SNIPPET_IMPORT)].flatMap((match) => {
-    const name = match.groups?.name;
-    const importSource = match.groups?.source;
-    if (!(name && importSource)) {
-      return [];
-    }
-    return [{ importText: match[0], name, source: importSource }];
-  });
-
-const collectVariableImports = (source: string): SnippetVariableImport[] =>
-  [...source.matchAll(NAMED_SNIPPET_IMPORT)].flatMap((match) => {
-    const names = match.groups?.names;
-    const importSource = match.groups?.source;
-    if (!(names && importSource)) {
-      return [];
-    }
-    const parsedNames = names.split(",").flatMap((entry) => {
-      const [imported, local] = entry.trim().split(/\s+as\s+/u);
-      return imported ? [{ imported, local: local ?? imported }] : [];
-    });
-    return parsedNames.length
-      ? [{ names: parsedNames, source: importSource }]
-      : [];
-  });
-
-const decodeStringLiteral = (value: string): string =>
-  value
-    .replaceAll("\\n", "\n")
-    .replaceAll("\\r", "\r")
-    .replaceAll("\\t", "\t")
-    .replaceAll(/\\(?<escaped>[\\'"`])/gu, "$<escaped>");
-
-const collectStringExports = (source: string): Map<string, string> => {
-  const exports = new Map<string, string>();
-  for (const match of source.matchAll(EXPORTED_STRING_CONST)) {
-    const name = match.groups?.name;
-    const value =
-      match.groups?.double ?? match.groups?.single ?? match.groups?.template;
-    if (name && value !== undefined) {
-      exports.set(name, decodeStringLiteral(value));
-    }
-  }
-  return exports;
-};
-
-const parseAttributes = (source: string): Record<string, string> => {
-  const props: Record<string, string> = {};
-  for (const match of source.matchAll(ATTRIBUTE)) {
-    const name = match.groups?.name;
-    if (!name) {
-      continue;
-    }
-    props[name] =
-      match.groups?.quoted ??
-      match.groups?.single ??
-      match.groups?.expression?.trim() ??
-      "true";
-  }
-  return props;
-};
-
-const interpolateProps = (
-  source: string,
-  props: Record<string, string>
-): string =>
-  source.replaceAll(PLACEHOLDER, (value, name: string) => props[name] ?? value);
-
-const stripImport = (source: string, importText: string): string =>
-  // Seam-targeted removal: a whole-document `\n{3,}` collapse would rewrite
-  // real double blank lines inside the page's code fences.
-  stripImports(source, new RegExp(escapeRegExp(importText), "gu"));
-
-const replacePlaceholder = (
-  source: string,
-  name: string,
-  value: string
-): string =>
-  source.replaceAll(new RegExp(`\\{${escapeRegExp(name)}\\}`, "gu"), value);
-
-const inlineSnippetTags = (options: {
-  name: string;
-  snippet: string;
-  source: string;
-}): string => {
-  const inline = (_value: string, attrs: string): string =>
-    interpolateProps(options.snippet, parseAttributes(attrs));
-  return options.source
-    .replaceAll(snippetSelfClosingTagPattern(options.name), inline)
-    .replaceAll(snippetPairedTagPattern(options.name), inline);
-};
-
-/**
- * Mintlify markdown snippets are source-level includes, not standalone pages.
- * Inline markdown snippets before Astro MDX compiles so `.md` imports, nested
- * markdown snippets, and `{prop}` interpolation inside prose or code fences work.
- */
-export const rewriteMintlifyMarkdownSnippets = async (
-  source: string,
-  options: SnippetTransformOptions
-): Promise<string> => {
-  const loadSnippet = async (file: string): Promise<string> => {
-    const seen = options.seen ?? new Set<string>();
-    if (seen.has(file)) {
-      throw new Error(
-        snippetCycleMessage(options.root, file, options.trail ?? [])
-      );
-    }
-    seen.add(file);
-    const readFile =
-      options.readFile ??
-      ((path: string): Promise<string> => readFileFromDisk(path, "utf-8"));
-    try {
-      let raw: string;
-      try {
-        raw = await readFile(file);
-      } catch {
-        // A dangling import must fail with a message that names both ends —
-        // the caller downgrades it to a per-page warning and moves on.
-        throw new Error(
-          `snippet ${rootRelativePath(options.root, file)} (imported by ${rootRelativePath(options.root, options.filePath)}) does not exist`
-        );
-      }
-      const content = matter(raw).content.trim();
-      const transformed = await rewriteMintlifyMarkdownSnippets(content, {
-        ...options,
-        filePath: file,
-        seen,
-        trail: [...(options.trail ?? []), file],
-      });
-      return transformed.trim();
-    } finally {
-      seen.delete(file);
-    }
-  };
-
-  const inlineImport = async (
-    current: string,
-    snippetImport: SnippetImport
-  ): Promise<string> => {
-    const file = resolveSnippetPath({
-      filePath: options.filePath,
-      root: options.root,
-      source: snippetImport.source,
-    });
-    if (!file) {
-      return current;
-    }
-
-    const snippet = await loadSnippet(file);
-    const next = inlineSnippetTags({
-      name: snippetImport.name,
-      snippet,
-      source: current,
-    });
-    return next === current
-      ? current
-      : stripImport(next, snippetImport.importText);
-  };
-
-  const imports = collectImports(source);
-  const inlineAt = async (index: number, current: string): Promise<string> => {
-    const snippetImport = imports[index];
-    if (!snippetImport) {
-      return current;
-    }
-    return inlineAt(index + 1, await inlineImport(current, snippetImport));
-  };
-
-  return await inlineAt(0, source);
-};
-
-/** Resolve imported string constants from Mintlify snippets for generated text. */
-export const rewriteMintlifySnippetVariables = async (
-  source: string,
-  options: SnippetTransformOptions
-): Promise<string> => {
-  const readFile = options.readFile ?? readFileFromDisk;
-  const inlineImport = async (
-    current: string,
-    variableImport: SnippetVariableImport
-  ): Promise<string> => {
-    const file = resolveSnippetPath({
-      filePath: options.filePath,
-      root: options.root,
-      source: variableImport.source,
-    });
-    if (!file) {
-      return current;
-    }
-
-    const exports = collectStringExports(matter(await readFile(file)).content);
-    let next = current;
-    for (const name of variableImport.names) {
-      const value = exports.get(name.imported);
-      if (value !== undefined) {
-        next = replacePlaceholder(next, name.local, value);
-      }
-    }
-    return next;
-  };
-
-  const imports = collectVariableImports(source);
-  const inlineAt = async (index: number, current: string): Promise<string> => {
-    const variableImport = imports[index];
-    if (!variableImport) {
-      return current;
-    }
-    return inlineAt(index + 1, await inlineImport(current, variableImport));
-  };
-
-  return await inlineAt(0, source);
-};
-
-/** Replace docs.json Mintlify globals such as `{{product-name}}`. */
-export const rewriteMintlifyGlobalVariables = (
-  source: string,
-  variables: Record<string, string>
-): string =>
-  source.replaceAll(GLOBAL_VARIABLE, (value, name: string) =>
-    Object.hasOwn(variables, name) ? (variables[name] ?? value) : value
-  );
-
-/** Mintlify exposes a logged-out `user` object to MDX personalization code. */
-export const rewriteMintlifyUserVariable = (source: string): string => {
-  if (USER_EXPORT.test(source)) {
-    return source;
-  }
-
-  const frontmatter = source.match(FRONTMATTER_BLOCK)?.[0] ?? "";
-  const body = (
-    frontmatter ? source.slice(frontmatter.length) : source
-  ).replace(/^\r?\n/u, "");
-  return `${frontmatter}export const user = {};\n\n${body}`;
-};

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);
-};