blume 0.5.3 → 0.5.4

package/src/components/content/ResponseField.astro

@@ -1,23 +0,0 @@
----
-// Mintlify-compat <ResponseField>: a named field (`name`, `type`, `required`,
-// `default`, `deprecated`) with its description in the slot.
-import ApiField from "./ApiField.astro";
-
-const {
-  default: defaultValue,
-  deprecated,
-  name,
-  required,
-  type,
-} = Astro.props;
----
-
-<ApiField
-  default={defaultValue}
-  deprecated={deprecated}
-  name={name}
-  required={required}
-  type={type}
->
-  <slot />
-</ApiField>

package/src/components/content/Warning.astro

@@ -1,9 +0,0 @@
----
-import Callout from "./Callout.astro";
-
-const { title } = Astro.props;
----
-
-<Callout title={title} type="warning">
-  <slot />
-</Callout>

package/src/core/assets.ts

@@ -1,31 +0,0 @@
-import { join } from "pathe";
-
-/** A static directory served at a URL prefix, in addition to `public/`. */
-export interface AssetMount {
-  /** Absolute filesystem path to the source directory (or file). */
-  dir: string;
-  /** URL path prefix the source is served at, e.g. `/images`. */
-  url: string;
-}
-
-/**
- * Resolve `content.assets` entries (top-level dirs served at the site root,
- * alongside `public/`) to `{ dir, url }` mounts. Shared by the generated Astro
- * runtime (dev middleware + build copy) and by link validation, so all three
- * agree on where a `/images/foo.png` reference resolves on disk.
- *
- * Each entry is normalized to a leading-slash URL and joined to the project
- * root; leading `./` or `/` and any `..` segments are stripped so a mount can't
- * escape the root or collide with the site's own routing prefix.
- */
-export const resolveAssetMounts = (
-  root: string,
-  assets: string[]
-): AssetMount[] =>
-  assets.map((entry) => {
-    const rel = entry
-      .replace(/^[./]+/u, "")
-      .replaceAll(/\.\.\/?/gu, "")
-      .replace(/\/+$/u, "");
-    return { dir: join(root, rel), url: `/${rel}` };
-  });

package/src/core/bridge.ts

@@ -1,102 +0,0 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-
-import { join } from "pathe";
-
-import { assetSegments } from "../migrate/mintlify/assets.ts";
-import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
-import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
-import type { BlumeConfig } from "./schema.ts";
-
-/** A detected docs-tool config that Blume can serve without a migration. */
-export interface BridgeDetection {
-  /** Which foreign docs tool was detected. */
-  tool: "mintlify";
-  /** Absolute path of the detected config file (`docs.json`/`mint.json`). */
-  configFile: string;
-  /** A Blume config synthesized from the foreign config, ready to validate. */
-  raw: BlumeConfig;
-}
-
-const MINTLIFY_CONFIG_FILES = ["docs.json", "mint.json"];
-
-/**
- * Detect a Mintlify project at `root` and synthesize an equivalent Blume config.
- *
- * "Bridge mode" lets a team swap `mintlify dev` for `blume dev` with no file
- * changes: `docs.json` is translated to Blume config (`loadMintlifyConfig`) and
- * its content block is rewired to a single `mintlify` content source, which
- * transforms each MDX page to Blume idiom at scan time. The original
- * `content.root`/`exclude` and `variables` move onto the source (Blume has no
- * runtime variable substitution, so globals are inlined into content there).
- *
- * Returns `null` when no Mintlify config is present. Only called when no
- * `blume.config.*` exists, so an explicit Blume config always takes precedence.
- */
-export const detectMintlifyBridge = async (
-  root: string
-): Promise<BridgeDetection | null> => {
-  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join(root, name)).find(
-    (candidate) => existsSync(candidate)
-  );
-  if (!configFile) {
-    return null;
-  }
-
-  const config = await loadMintlifyConfig(root, configFile);
-
-  // i18n is derived from the raw spec (language dirs), mirroring the migrator.
-  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"
-      );
-    }
-  }
-
-  const variables = (config.variables as Record<string, string>) ?? {};
-  const root_ = config.content?.root ?? ".";
-  const exclude = config.content?.exclude ?? [];
-
-  // Mintlify serves assets from the project root; the bridge never moves files,
-  // so referenced root-level asset folders (e.g. `images/`) are served in place
-  // via `content.assets` instead. This is the read-only twin of the migrator's
-  // relocation — same referenced segments, just no `public/` move.
-  const assets = assetSegments(config).filter(
-    (segment) => segment !== "public" && existsSync(join(root, segment))
-  );
-
-  return {
-    configFile,
-    raw: {
-      ...config,
-      content: {
-        assets,
-        // Mirror the excludes onto `content.exclude` too: the generated Astro
-        // `docs` collection globs `content.root` (here the project root) and
-        // must skip node_modules/snippets just like the source does.
-        exclude,
-        root: root_,
-        sources: [
-          {
-            configFile,
-            exclude,
-            root: root_,
-            type: "mintlify",
-            variables,
-          },
-        ],
-      },
-      // Globals are inlined into content by the source; drop the top-level copy.
-      variables: undefined,
-    },
-    tool: "mintlify",
-  };
-};

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