blume 0.5.3 → 0.6.0

package/src/core/sources/mintlify.ts

@@ -1,190 +0,0 @@
-import { existsSync, watch as fsWatch } from "node:fs";
-import type { WatchListener } from "node:fs";
-import { readFile } from "node:fs/promises";
-
-import { isAbsolute, join, relative, resolve } from "pathe";
-import { glob } from "tinyglobby";
-
-import { transformMintlifyContent } from "../../migrate/mintlify/transform.ts";
-import { BlumeError } from "../diagnostics.ts";
-import matter from "../frontmatter.ts";
-import type { Diagnostic } from "../types.ts";
-import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
-import { BLUME_WATCH_IGNORE_DIRS, ignoringWatchListener } from "./watch.ts";
-
-/** Options for the Mintlify bridge content source. */
-export interface MintlifySourceOptions {
-  /** Stable source name; namespaces ids and diagnostics. */
-  name: string;
-  /** Optional route prefix. */
-  prefix?: string;
-  /** Content root, absolute or relative to `projectRoot` (Mintlify: `.`). */
-  root: string;
-  include: string[];
-  exclude: string[];
-  /** `docs.json` variables, inlined into content (`{{name}}`) at scan time. */
-  variables: Record<string, string>;
-  /** Absolute path of the `docs.json`/`mint.json`, watched for changes in dev. */
-  configFile?: string;
-  /** Absolute project root, used to resolve a relative `root`. */
-  projectRoot: string;
-}
-
-/**
- * Folders Mintlify projects keep alongside content that are never pages:
- * snippets are inlined as includes, and build/tooling dirs are noise. Merged
- * with the user's `exclude` so bridge mode behaves like the one-shot migrator.
- */
-const MINTLIFY_SOURCE_IGNORES = [
-  "node_modules/**",
-  ".blume/**",
-  "dist/**",
-  "build/**",
-  "public/**",
-  "snippets/**",
-];
-
-/**
- * Directory names the recursive dev watcher must ignore, on top of the shared
- * {@link BLUME_WATCH_IGNORE_DIRS} (Blume's own `.blume/` output, VCS,
- * dependencies). Derived from {@link MINTLIFY_SOURCE_IGNORES} so bridge mode's
- * watcher stays in sync with what its scan skips (snippets, build output, …).
- */
-const WATCH_IGNORE_DIRS = [
-  ...BLUME_WATCH_IGNORE_DIRS,
-  ...MINTLIFY_SOURCE_IGNORES.map((pattern) => pattern.replace(/\/\*\*$/u, "")),
-];
-
-/**
- * Build the recursive-watch listener for the bridge source: ignore events under
- * {@link WATCH_IGNORE_DIRS} so the dev server's `.blume/` writes don't feed a
- * regeneration loop. Exported for testing.
- */
-export const mintlifyWatchListener = (
-  onChange: () => void
-): WatchListener<string> => ignoringWatchListener(onChange, WATCH_IGNORE_DIRS);
-
-/**
- * The Mintlify bridge content source. Reads an unconverted Mintlify project in
- * place and transforms each page to Blume MDX at scan time (callouts → `:::`
- * directives, snippet/variable inlining, etc.) via `transformMintlifyContent`.
- * Staged: the transformed bodies are materialized under `.blume/content` and
- * rendered through Astro's `staged` collection, so the rewrites actually reach
- * the output. Components Blume already ships (Card, Tabs, Steps, …) render as-is.
- */
-export const mintlifySource = (
-  options: MintlifySourceOptions
-): ContentSource & { readonly contentRoot: string } => {
-  const contentRoot = isAbsolute(options.root)
-    ? options.root
-    : join(resolve(options.projectRoot), options.root);
-  const ignore = [...new Set([...options.exclude, ...MINTLIFY_SOURCE_IGNORES])];
-
-  const transform = (
-    raw: string,
-    file: string
-  ): ReturnType<typeof transformMintlifyContent> =>
-    transformMintlifyContent(raw, {
-      filePath: file,
-      root: resolve(options.projectRoot),
-      variables: options.variables,
-    });
-
-  const load = async (): Promise<SourceLoadResult> => {
-    const files = await glob(options.include, {
-      absolute: true,
-      cwd: contentRoot,
-      ignore,
-      onlyFiles: true,
-    });
-    files.sort();
-
-    const unsupported = new Set<string>();
-    const entries = await Promise.all(
-      files.map(async (file): Promise<SourceEntry> => {
-        const result = await transform(await readFile(file, "utf-8"), file);
-        for (const name of result.unsupported) {
-          unsupported.add(name);
-        }
-        const parsed = matter(result.content);
-        // Force MDX: Mintlify pages are MDX-authored and the rewrites emit `:::`
-        // directives + JSX, neither of which the plain `.md` processor expands.
-        return {
-          body: { format: "mdx", text: parsed.content },
-          data: parsed.data,
-          raw: result.content,
-          ref: relative(contentRoot, file),
-          sourcePath: file,
-        };
-      })
-    );
-
-    const diagnostics: Diagnostic[] =
-      unsupported.size > 0
-        ? [
-            {
-              code: "BLUME_MINTLIFY_UNSUPPORTED",
-              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Replace them by hand or provide a matching component.`,
-              severity: "warning",
-            },
-          ]
-        : [];
-
-    return { diagnostics, entries };
-  };
-
-  const validate = (): void => {
-    if (!existsSync(contentRoot)) {
-      throw new BlumeError({
-        code: "BLUME_CONTENT_ROOT_MISSING",
-        file: contentRoot,
-        message: `Content root not found: ${options.root}`,
-        severity: "error",
-        suggestion: `Run "blume dev" from the directory that contains docs.json.`,
-      });
-    }
-  };
-
-  const watch = (onChange: () => void): (() => void) => {
-    const disposers: (() => void)[] = [];
-    if (existsSync(contentRoot)) {
-      // Recursively watch the content root, but skip Blume's own output and
-      // other non-content trees so the dev server's `.blume/` writes don't feed
-      // a regeneration loop (`fs.watch` has no ignore option, so filter here).
-      const watcher = fsWatch(
-        contentRoot,
-        { recursive: true },
-        mintlifyWatchListener(onChange)
-      );
-      disposers.push(() => watcher.close());
-    }
-    // Watch docs.json directly: it lives at the content root but a non-recursive
-    // single-file watch fires reliably on edits that recursive dir-watch can miss.
-    if (options.configFile && existsSync(options.configFile)) {
-      const watcher = fsWatch(options.configFile, onChange);
-      disposers.push(() => watcher.close());
-    }
-    return () => {
-      for (const dispose of disposers) {
-        dispose();
-      }
-    };
-  };
-
-  const read = async (ref: string): Promise<string> => {
-    const file = join(contentRoot, ref);
-    const result = await transform(await readFile(file, "utf-8"), file);
-    return result.content;
-  };
-
-  return {
-    contentRoot,
-    load,
-    name: options.name,
-    prefix: options.prefix,
-    read,
-    staged: true,
-    validate,
-    watch,
-  };
-};

package/src/migrate/fumadocs/config.ts

@@ -1,155 +0,0 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-
-import { basename, dirname, join } from "pathe";
-
-import type { BlumeConfig } from "../../core/schema.ts";
-
-/**
- * Build a `BlumeConfig` for a Fumadocs project. Fumadocs is code-first — its
- * navigation comes from the folder tree plus `meta.json` files, not a JSON
- * config — so there is little to translate. We take the title from
- * `package.json` and scrape the `loader({ baseUrl })` route prefix from the
- * source loader so migrated routes keep serving under `/<baseUrl>`. The source
- * files are TypeScript, so we read by pattern rather than executing them.
- */
-
-/** Loader files that may hold `loader({ baseUrl: "/docs" })`. */
-const SOURCE_FILES = [
-  "lib/source.ts",
-  "app/source.ts",
-  "src/lib/source.ts",
-  "src/app/source.ts",
-  "source.ts",
-];
-
-const BASE_URL = /baseUrl\s*:\s*['"`](?<base>[^'"`]+)['"`]/u;
-
-/** Title-case a package name (drop any scope) into a readable doc title. */
-const prettifyTitle = (name: string): string => {
-  const base = name.includes("/")
-    ? name.slice(name.lastIndexOf("/") + 1)
-    : name;
-  const words = base.split(/[-_\s]+/u).filter(Boolean);
-  if (words.length === 0) {
-    return "Documentation";
-  }
-  return words
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(" ");
-};
-
-/**
- * Generic monorepo app-shell package names. When the migrated project is named
- * one of these, its name makes a poor doc title ("Web"), so we fall back to the
- * repo name — but only in a monorepo, where a better name is actually available.
- */
-const GENERIC_NAMES = new Set([
-  "api",
-  "app",
-  "client",
-  "frontend",
-  "server",
-  "site",
-  "web",
-  "www",
-]);
-
-/** The nearest ancestor that is a git repository root, or null. */
-const gitRepoRoot = (start: string): string | null => {
-  let dir = start;
-  for (;;) {
-    if (existsSync(join(dir, ".git"))) {
-      return dir;
-    }
-    const parent = dirname(dir);
-    if (parent === dir) {
-      return null;
-    }
-    dir = parent;
-  }
-};
-
-/** The unscoped package name (`@acme/web` -> `web`). */
-const bareName = (name: string): string =>
-  name.includes("/") ? name.slice(name.lastIndexOf("/") + 1) : name;
-
-const readTitle = async (root: string): Promise<string> => {
-  const packageJson = join(root, "package.json");
-  if (!existsSync(packageJson)) {
-    return "Documentation";
-  }
-  try {
-    const parsed = JSON.parse(await readFile(packageJson, "utf-8")) as {
-      name?: unknown;
-    };
-    const { name } = parsed;
-    if (typeof name !== "string" || !name.trim()) {
-      return "Documentation";
-    }
-    // A generic name (`apps/web` -> "Web") is a weak title. In a monorepo the
-    // repo's own directory name is usually better, so prefer it when this isn't
-    // already the repo root.
-    if (GENERIC_NAMES.has(bareName(name).toLowerCase())) {
-      const repoRoot = gitRepoRoot(root);
-      if (repoRoot && repoRoot !== root) {
-        const repoTitle = prettifyTitle(basename(repoRoot));
-        if (repoTitle !== "Documentation") {
-          return repoTitle;
-        }
-      }
-    }
-    return prettifyTitle(name);
-  } catch {
-    return "Documentation";
-  }
-};
-
-const scrapeBaseUrl = async (root: string): Promise<string | null> => {
-  for (const candidate of SOURCE_FILES) {
-    const file = join(root, candidate);
-    if (!existsSync(file)) {
-      continue;
-    }
-    // oxlint-disable-next-line no-await-in-loop -- sequential probing of candidates
-    const base = BASE_URL.exec(await readFile(file, "utf-8"))?.groups?.base;
-    if (base) {
-      return base;
-    }
-  }
-  return null;
-};
-
-export interface FumadocsConfigResult {
-  config: BlumeConfig;
-  warnings: string[];
-}
-
-/** Resolve the Blume config and route prefix for a Fumadocs project. */
-export const loadFumadocsConfig = async (
-  root: string
-): Promise<FumadocsConfigResult> => {
-  const title = await readTitle(root);
-  const baseUrl = await scrapeBaseUrl(root);
-  // Default to the conventional Fumadocs `/docs` base when none is declared.
-  const prefix = (baseUrl ?? "docs").replaceAll(/^\/+|\/+$/gu, "");
-  const warnings: string[] = [];
-
-  if (prefix) {
-    warnings.push(
-      `Docs are served under /${prefix} (set content.sources prefix); change it to "" to serve from the site root.`
-    );
-    return {
-      config: {
-        content: {
-          sources: [{ prefix, root: "docs", type: "filesystem" }],
-        },
-        title,
-      },
-      warnings,
-    };
-  }
-
-  warnings.push("Docs are served from the site root.");
-  return { config: { title }, warnings };
-};