blume 0.5.2 → 0.5.4

package/src/migrate/fumadocs/groups.ts

@@ -1,237 +0,0 @@
-import { existsSync, statSync } from "node:fs";
-import { mkdir, rename, writeFile } from "node:fs/promises";
-
-import { basename, join } from "pathe";
-
-import { isInsideRoot } from "../shared.ts";
-import { renderMetaModule } from "./meta.ts";
-import type {
-  FumadocsPageItem,
-  FumadocsPagesStructure,
-  FumadocsSection,
-} from "./meta.ts";
-
-/**
- * Rebuild Fumadocs `---Section---` separators as Blume group folders.
- *
- * Fumadocs draws a non-collapsible section heading from a `"---Label---"` entry
- * in a folder's `pages` array — exactly what a Blume `(Label)/` group folder
- * renders by default (`display: "flat"`). Blume has no flat-file "separator"
- * primitive, so the only faithful, non-overriding home for a section is a group
- * folder: it is route-transparent (the `(Label)` segment is stripped from URLs,
- * see `core/sources/normalize.ts`) and composes with per-folder `meta.ts`,
- * unlike a global `navigation.sidebar` override (which would disable every other
- * folder's meta site-wide).
- *
- * The reshape runs against the already-migrated `docs/` tree, so each `pages`
- * entry is resolved to a real page file or folder before it is moved. A section
- * that is a single folder is left in place (wrapping it would double the
- * heading); links have no file to move and are dropped with a warning.
- */
-
-const PAGE_EXTS = [".mdx", ".md"];
-const WORD_SPLIT = /[-_]/u;
-const PATH_SEP = /[/\\]/u;
-
-interface ResolvedEntry {
-  kind: "file" | "folder";
-  path: string;
-}
-
-const isDirectory = (path: string): boolean => {
-  try {
-    return statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-};
-
-/** Resolve a `pages` name to its on-disk page file or folder under `docsDir`. */
-const resolveEntry = (docsDir: string, name: string): ResolvedEntry | null => {
-  // A `pages` entry is author-controlled; reject any that escapes `docsDir`
-  // (e.g. `"../../victim"`) so the later `rename` can't move a file out of the
-  // docs tree.
-  if (!isInsideRoot(docsDir, join(docsDir, name))) {
-    return null;
-  }
-  for (const ext of PAGE_EXTS) {
-    const file = join(docsDir, `${name}${ext}`);
-    if (existsSync(file)) {
-      return { kind: "file", path: file };
-    }
-  }
-  const folder = join(docsDir, name);
-  return isDirectory(folder) ? { kind: "folder", path: folder } : null;
-};
-
-const humanize = (name: string): string =>
-  name
-    .split(WORD_SPLIT)
-    .filter(Boolean)
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(" ");
-
-const linkWarning = (item: { href: string; text: string }): string =>
-  `Dropped sidebar link "${item.text}" (${item.href}) — add it to navbar.links manually.`;
-
-const extractWarning = (name: string): string =>
-  `Sidebar extract "...${name}" became a normal "${name}" group (its pages are not flattened into the parent).`;
-
-export interface GroupReshapeResult {
-  /** Ordering keys for the parent folder's `meta.ts` `pages`. */
-  order: string[];
-  warnings: string[];
-}
-
-/** Record an in-place item's ordering key (lead items, or an ungroupable run). */
-const addUngroupedItem = (
-  item: FumadocsPageItem,
-  order: string[],
-  warnings: string[]
-): void => {
-  if (item.kind === "link") {
-    warnings.push(linkWarning(item));
-    return;
-  }
-  if (item.kind === "extract") {
-    warnings.push(extractWarning(item.name));
-  }
-  order.push(item.name);
-};
-
-/** A section of one folder keeps its place without a wrapping group folder. */
-const reshapeSingleFolderSection = (
-  section: FumadocsSection,
-  only: FumadocsPageItem & { kind: "extract" | "ref" },
-  order: string[],
-  warnings: string[]
-): void => {
-  order.push(only.name);
-  if (humanize(only.name).toLowerCase() !== section.label.toLowerCase()) {
-    warnings.push(
-      `Section "${section.label}" wraps folder "${only.name}"; set that folder's meta title to "${section.label}" to make the heading match.`
-    );
-  }
-  if (only.kind === "extract") {
-    warnings.push(extractWarning(only.name));
-  }
-};
-
-/** Move one section item into the group folder; return its ordering key. */
-const moveItemIntoGroup = async (
-  item: FumadocsPageItem,
-  docsDir: string,
-  groupDir: string,
-  label: string,
-  warnings: string[]
-): Promise<string | null> => {
-  if (item.kind === "link") {
-    warnings.push(linkWarning(item));
-    return null;
-  }
-  const resolved = resolveEntry(docsDir, item.name);
-  if (!resolved) {
-    warnings.push(
-      `Sidebar entry "${item.name}" in section "${label}" matched no page or folder; skipped.`
-    );
-    return null;
-  }
-  const dest = join(groupDir, basename(resolved.path));
-  if (existsSync(dest)) {
-    warnings.push(
-      `Skipped moving "${item.name}" into section "${label}" (target already exists).`
-    );
-    return null;
-  }
-  await mkdir(groupDir, { recursive: true });
-  await rename(resolved.path, dest);
-  if (item.kind === "extract") {
-    warnings.push(extractWarning(item.name));
-  }
-  return item.name;
-};
-
-const reshapeSection = async (
-  section: FumadocsSection,
-  docsDir: string,
-  order: string[],
-  warnings: string[]
-): Promise<void> => {
-  const movable = section.items.filter((item) => item.kind !== "link");
-
-  // A lone folder already renders as its own group; wrapping it in a `(Label)/`
-  // folder would stack two headings, so leave it in place.
-  if (movable.length === 1) {
-    const [only] = movable as [FumadocsPageItem & { kind: "extract" | "ref" }];
-    if (resolveEntry(docsDir, only.name)?.kind === "folder") {
-      reshapeSingleFolderSection(section, only, order, warnings);
-      return;
-    }
-  }
-
-  if (PATH_SEP.test(section.label)) {
-    warnings.push(
-      `Section "${section.label}" has a slash in its name and can't become a group folder; its pages stay ungrouped.`
-    );
-    for (const item of section.items) {
-      addUngroupedItem(item, order, warnings);
-    }
-    return;
-  }
-
-  const groupDir = join(docsDir, `(${section.label})`);
-  const sectionKeys: string[] = [];
-  for (const item of section.items) {
-    // oxlint-disable-next-line no-await-in-loop -- sequential moves into one group
-    const key = await moveItemIntoGroup(
-      item,
-      docsDir,
-      groupDir,
-      section.label,
-      warnings
-    );
-    if (key) {
-      sectionKeys.push(key);
-    }
-  }
-
-  // Nothing movable (e.g. a link-only section) — drop the empty heading.
-  if (sectionKeys.length === 0) {
-    return;
-  }
-
-  // The group folder's key in the nav is its label, so order it by label.
-  order.push(section.label);
-  // Preserve the authored order of the section's pages.
-  if (sectionKeys.length > 1) {
-    await writeFile(
-      join(groupDir, "meta.ts"),
-      renderMetaModule({ pages: sectionKeys }),
-      "utf-8"
-    );
-  }
-};
-
-/**
- * Reshape a parsed `pages` structure into group folders under `docsDir`,
- * returning the parent folder's `meta.ts` page ordering and any warnings. Items
- * are moved within the already-migrated `docs/` tree, so this must run after the
- * pages have been moved out of `content/docs`.
- */
-export const reshapeFumadocsGroups = async (
-  structure: FumadocsPagesStructure,
-  docsDir: string
-): Promise<GroupReshapeResult> => {
-  const order: string[] = [];
-  const warnings: string[] = [];
-
-  for (const item of structure.lead) {
-    addUngroupedItem(item, order, warnings);
-  }
-  for (const section of structure.sections) {
-    // oxlint-disable-next-line no-await-in-loop -- sections share `docsDir` state
-    await reshapeSection(section, docsDir, order, warnings);
-  }
-
-  return { order, warnings };
-};

package/src/migrate/fumadocs/index.ts

@@ -1,340 +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. */
-const writeMeta = async (
-  dest: string,
-  meta: FolderMeta,
-  rel: string,
-  warnings: string[]
-): Promise<string[]> => {
-  if (Object.keys(meta).length === 0) {
-    return warnings;
-  }
-  if (existsSync(dest)) {
-    return [...warnings, `Skipped ${rel} (target already exists)`];
-  }
-  await mkdir(dirname(dest), { recursive: true });
-  await writeFile(dest, renderMetaModule(meta), "utf-8");
-  return 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,
-    ]);
-    await rm(abs, { force: true });
-    return result;
-  }
-
-  const { meta, warnings } = translateFumadocsMeta(parsed);
-  const result = await writeMeta(dest, meta, rel, warnings);
-  await rm(abs, { force: true });
-  return result;
-};
-
-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 };
-};