blume 0.5.2 → 0.5.4

package/src/migrate/mintlify/index.ts

@@ -1,372 +0,0 @@
-import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-
-import { dirname, join } from "pathe";
-import { glob } from "tinyglobby";
-
-import { ensureGitignore } from "../../core/gitignore.ts";
-import type { BlumeConfig } from "../../core/schema.ts";
-import { ensurePackageJson } from "../shared.ts";
-import { assetSegments } from "./assets.ts";
-import { loadMintlifyConfig, partitionMintlifyRedirects } from "./config.ts";
-import { mintlifyI18n } from "./i18n.ts";
-import { transformMintlifyContent } from "./transform.ts";
-
-export interface MintlifyMigrationResult {
-  moved: number;
-  warnings: string[];
-}
-
-const asRecord = (value: unknown): Record<string, unknown> | undefined =>
-  value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-
-const hasFontFamily = (value: unknown): boolean => {
-  const object = asRecord(value);
-  if (!object) {
-    return false;
-  }
-  const named = (child: unknown): boolean =>
-    typeof asRecord(child)?.family === "string";
-  return (
-    typeof object.family === "string" ||
-    named(object.heading) ||
-    named(object.body)
-  );
-};
-
-/**
- * Warn about Mintlify site chrome that Blume's config doesn't model, so it isn't
- * dropped silently: header links (`navbar.links`/`navbar.primary`), footer
- * socials (`footer.socials`), and fonts outside Blume's curated Google set. The
- * contextual page menu and last-updated timestamp are covered by Blume defaults
- * (page actions, git-derived dates), so they need no warning.
- */
-const droppedChromeWarnings = (
-  spec: Record<string, unknown>,
-  config: BlumeConfig
-): string[] => {
-  const warnings: string[] = [];
-  const navbar = asRecord(spec.navbar);
-  if (navbar && (navbar.links || navbar.primary)) {
-    warnings.push(
-      "Header links (navbar.links/navbar.primary) have no blume.config equivalent and were dropped; re-add them with navigation.tabs or a Header layout override."
-    );
-  }
-  if (asRecord(spec.footer)?.socials) {
-    warnings.push(
-      "Footer social links (footer.socials) have no blume.config equivalent and were dropped; add them with a Footer layout override."
-    );
-  }
-  if (hasFontFamily(spec.fonts ?? spec.font) && !config.theme?.fonts) {
-    warnings.push(
-      "docs.json font family isn't in Blume's curated Google Fonts set; set theme.fonts to a supported slug or add @font-face rules in theme.css."
-    );
-  }
-  return warnings;
-};
-
-/**
- * Warn about dynamic (wildcard/param) redirects the migrator dropped. Blume
- * redirects are static path-to-path, so a `:slug*`/`:id` source becomes an
- * unroutable Astro destination — kept ones crash the build. Point the user at
- * host-level rules that do support wildcards.
- */
-const droppedRedirectWarnings = (spec: Record<string, unknown>): string[] => {
-  const { dropped } = partitionMintlifyRedirects(spec);
-  if (dropped.length === 0) {
-    return [];
-  }
-  return [
-    `Dropped ${dropped.length} dynamic redirect(s) Blume can't model as static path-to-path (${dropped.join(", ")}); re-add them as host-level rules (e.g. _redirects or vercel.json).`,
-  ];
-};
-
-/** 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");
-};
-
-interface RelocatedAssets {
-  /** Top-level dirs served in place via `content.assets` (no files moved). */
-  served: string[];
-  /** Top-level files moved under `public/`. */
-  moved: string[];
-}
-
-/**
- * Make referenced top-level assets resolvable in Blume. Directories (e.g.
- * Mintlify's `images/`) are left in place and served via `content.assets`, so
- * the migration doesn't churn every file under them; loose top-level files
- * (a root `favicon.png`, `logo.png`) are moved under `public/` since a mount
- * points at a directory.
- */
-const relocateAssets = async (
-  root: string,
-  segments: string[]
-): Promise<RelocatedAssets> => {
-  const served: string[] = [];
-  const moved: string[] = [];
-  for (const segment of segments) {
-    const source = join(root, segment);
-    if (!existsSync(source) || segment === "public") {
-      continue;
-    }
-    // oxlint-disable-next-line no-await-in-loop -- sequential fs stats
-    const stats = await stat(source);
-    if (stats.isDirectory()) {
-      served.push(segment);
-      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, served };
-};
-
-/**
- * Fold relocated assets into the config (served dirs become `content.assets`)
- * and record what happened. Served dirs stay in place; only loose files moved.
- */
-const applyRelocatedAssets = (
-  config: BlumeConfig,
-  assets: RelocatedAssets,
-  warnings: string[]
-): void => {
-  if (assets.served.length > 0) {
-    config.content = {
-      ...config.content,
-      assets: [
-        ...new Set([...(config.content?.assets ?? []), ...assets.served]),
-      ],
-    };
-    warnings.push(
-      `Kept asset dir(s) in place, served via content.assets: ${assets.served.join(", ")}.`
-    );
-  }
-  if (assets.moved.length > 0) {
-    warnings.push(`Moved assets into public/: ${assets.moved.join(", ")}.`);
-  }
-};
-
-/**
- * Scaffold the project files a config-only Mintlify repo lacks: a runnable
- * `package.json` (it ships no npm manifest) and a `.gitignore` for Blume's
- * generated `.blume/` runtime and `dist/` build output. Both are idempotent —
- * an existing file is extended, not overwritten — and noted in the warnings.
- */
-const scaffoldProjectFiles = async (
-  root: string,
-  warnings: string[]
-): Promise<void> => {
-  if (await ensurePackageJson(root)) {
-    warnings.push(
-      "Created a package.json with blume as a dependency; run `npm install`, then `npm run dev`."
-    );
-  }
-  const ignored = await ensureGitignore(root, [".blume/", "dist/"]);
-  if (ignored.length > 0) {
-    warnings.push(`Added ${ignored.join(", ")} to .gitignore.`);
-  }
-};
-
-/**
- * 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.`
-    );
-  }
-};
-
-/**
- * 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.`
-      );
-    }
-    const openapiSources = config.openapi?.sources ?? [];
-    if (openapiSources.length > 0) {
-      warnings.push(
-        `Mapped ${openapiSources.length} OpenAPI spec source(s) to openapi.sources (native reference renderer); verify each spec path or URL resolves.`
-      );
-    }
-    warnings.push(...droppedChromeWarnings(spec, config));
-    warnings.push(...droppedRedirectWarnings(spec));
-  } 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 assets = await relocateAssets(root, assetSegments(config));
-  await cleanupSnippets(root, keptComponents, warnings);
-
-  if (config.content?.exclude) {
-    config.content.exclude = [...new Set(config.content.exclude)];
-  }
-  applyRelocatedAssets(config, assets, warnings);
-  await writeBlumeConfig(root, config);
-  await scaffoldProjectFiles(root, warnings);
-
-  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 (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: ${[...unsupported].join(", ")}.`
-    );
-  }
-  warnings.push(
-    "Review blume.config.ts; navigation, theme, and chrome were mapped from docs.json."
-  );
-
-  return { moved, warnings };
-};

package/src/migrate/mintlify/snippets.ts

@@ -1,306 +0,0 @@
-import { readFile as readFileFromDisk } from "node:fs/promises";
-
-import { dirname, relative, resolve } from "pathe";
-
-import matter from "../../core/frontmatter.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 isInsideRoot = (root: string, candidate: string): boolean => {
-  const rel = relative(root, candidate);
-  return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/"));
-};
-
-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 =>
-  source.replace(importText, "").replaceAll(/\n{3,}/gu, "\n\n");
-
-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 ?? readFileFromDisk;
-    try {
-      const raw = await readFile(file);
-      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}`;
-};