blume 0.0.0 → 0.1.0

package/src/markdown/package-commands.ts

@@ -0,0 +1,159 @@
+/** Supported package managers, in the order tabs are displayed. */
+export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+
+/** Words that mark the input as an explicit command rather than a bare list. */
+const MANAGER_PREFIXES = new Set(["bun", "bunx", "npm", "npx", "pnpm", "yarn"]);
+
+const WHITESPACE = /\s+/u;
+const WHITESPACE_RUN = /\s+/gu;
+const GLOBAL_FLAGS = new Set(["-g", "--global"]);
+
+type Operation = "add" | "create" | "exec" | "install" | "remove" | "run";
+
+interface Intent {
+  args: string[];
+  operation: Operation;
+}
+
+/** Map a package-manager subcommand to a normalized operation. */
+const normalizeVerb = (verb: string): Operation | null => {
+  switch (verb) {
+    case "add":
+    case "i":
+    case "in":
+    case "install": {
+      return "add";
+    }
+    case "create":
+    case "init": {
+      return "create";
+    }
+    case "dlx":
+    case "exec":
+    case "x": {
+      return "exec";
+    }
+    case "remove":
+    case "rm":
+    case "un":
+    case "uninstall": {
+      return "remove";
+    }
+    case "run": {
+      return "run";
+    }
+    default: {
+      return null;
+    }
+  }
+};
+
+/** Normalize npm-style flags to forms every manager understands. */
+const normalizeFlags = (args: string[]): string[] =>
+  args.flatMap((arg) => {
+    if (arg === "--save-dev") {
+      return ["-D"];
+    }
+    if (arg === "--save" || arg === "-S") {
+      return [];
+    }
+    return [arg];
+  });
+
+/**
+ * Parse an input command (a bare package list like `react react-dom` or an
+ * explicit command like `npm i -D typescript` / `npx astro add`) into a
+ * manager-agnostic intent.
+ */
+const parseIntent = (input: string): Intent => {
+  const tokens = input.trim().split(WHITESPACE).filter(Boolean);
+  if (tokens.length === 0) {
+    return { args: [], operation: "install" };
+  }
+
+  const [first, ...rest] = tokens;
+  if (first === undefined) {
+    return { args: [], operation: "install" };
+  }
+  if (!MANAGER_PREFIXES.has(first)) {
+    return { args: normalizeFlags(tokens), operation: "add" };
+  }
+  if (first === "npx" || first === "bunx") {
+    return { args: rest, operation: "exec" };
+  }
+
+  const [verb, ...verbArgs] = rest;
+  if (!verb) {
+    return { args: [], operation: "install" };
+  }
+  const operation = normalizeVerb(verb);
+  if (operation === null) {
+    // Unknown subcommand (e.g. `npm test`); run it as a script.
+    return { args: rest, operation: "run" };
+  }
+  if (operation === "add" && verbArgs.length === 0) {
+    return { args: [], operation: "install" };
+  }
+  return { args: normalizeFlags(verbArgs), operation };
+};
+
+/** Render one manager's command for the given intent. */
+const buildCommand = (manager: PackageManager, intent: Intent): string => {
+  const args = intent.args.join(" ");
+  switch (intent.operation) {
+    case "add": {
+      if (manager === "npm") {
+        return `npm install ${args}`;
+      }
+      if (manager === "yarn" && intent.args.some((a) => GLOBAL_FLAGS.has(a))) {
+        const pkgs = intent.args.filter((a) => !GLOBAL_FLAGS.has(a)).join(" ");
+        return `yarn global add ${pkgs}`;
+      }
+      return `${manager} add ${args}`;
+    }
+    case "create": {
+      return `${manager} create ${args}`;
+    }
+    case "exec": {
+      if (manager === "npm") {
+        return `npx ${args}`;
+      }
+      if (manager === "bun") {
+        return `bunx ${args}`;
+      }
+      return `${manager} dlx ${args}`;
+    }
+    case "remove": {
+      return manager === "npm"
+        ? `npm uninstall ${args}`
+        : `${manager} remove ${args}`;
+    }
+    case "run": {
+      return `${manager} run ${args}`;
+    }
+    default: {
+      return `${manager} install`;
+    }
+  }
+};
+
+/**
+ * Convert an install command into the equivalent for every supported package
+ * manager. Accepts a bare package list (`react`) or a full command
+ * (`npm i -D typescript`, `npx astro add react`).
+ */
+export const toPackageCommands = (
+  input: string
+): Record<PackageManager, string> => {
+  const intent = parseIntent(input);
+  const normalize = (command: string): string =>
+    command.replaceAll(WHITESPACE_RUN, " ").trim();
+  return {
+    bun: normalize(buildCommand("bun", intent)),
+    npm: normalize(buildCommand("npm", intent)),
+    pnpm: normalize(buildCommand("pnpm", intent)),
+    yarn: normalize(buildCommand("yarn", intent)),
+  };
+};

package/src/markdown/package-install.ts

@@ -0,0 +1,40 @@
+import { codeBlock, jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+import { PACKAGE_MANAGERS, toPackageCommands } from "./package-commands.ts";
+
+interface CodeNode extends MdastNode {
+  lang?: string | null;
+  value: string;
+}
+
+/** Build an `<Tab title="...">` node wrapping a single highlighted command. */
+const tabNode = (manager: string, command: string) =>
+  jsxFlowElement(
+    "Tab",
+    [jsxAttribute("title", manager)],
+    [codeBlock("bash", command)]
+  );
+
+/**
+ * Satteri MDAST plugin that turns a ` ```package-install ` code block into a
+ * `<Tabs>` group with one `<Tab>` per package manager, each holding the
+ * converted install command as a normal (highlighted) code block. Runs at the
+ * MDAST stage so the generated code blocks are highlighted like any other.
+ */
+export const packageInstallPlugin = () => ({
+  code(node: CodeNode, ctx: MdastVisitorContext) {
+    if (node.lang !== "package-install") {
+      return;
+    }
+    const commands = toPackageCommands(node.value);
+    ctx.replaceNode(
+      node,
+      jsxFlowElement(
+        "Tabs",
+        [],
+        PACKAGE_MANAGERS.map((manager) => tabNode(manager, commands[manager]))
+      )
+    );
+  },
+  name: "blume-package-install",
+});

package/src/migrate/fumadocs/config.ts

@@ -0,0 +1,106 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+
+import { 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(" ");
+};
+
+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;
+    };
+    return typeof parsed.name === "string" && parsed.name.trim()
+      ? prettifyTitle(parsed.name)
+      : "Documentation";
+  } 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 };
+};

package/src/migrate/fumadocs/content.ts

@@ -0,0 +1,365 @@
+import { existsSync } from "node:fs";
+import { readFile as readFileFromDisk } from "node:fs/promises";
+
+import matter from "gray-matter";
+import { dirname, resolve } from "pathe";
+
+import { findOpenTagEnd, renameTag, rewriteCallouts } from "../shared.ts";
+
+/**
+ * Source-to-source rewrites that turn Fumadocs-only MDX into idiomatic Blume
+ * markup. Runs once at migration time — no Fumadocs-aware plugins remain in the
+ * Blume runtime.
+ */
+
+// ---------------------------------------------------------------------------
+// Imports
+// ---------------------------------------------------------------------------
+
+const FUMADOCS_IMPORT =
+  /^import\s+[\s\S]*?\s+from\s+["']fumadocs-(?:ui|core|mdx)(?:\/[^"']*)?["'];?[ \t]*\n?/gmu;
+
+/**
+ * Drop `import … from "fumadocs-ui/…"` (and `-core`/`-mdx`) statements. Blume
+ * injects its components globally, so these imports would fail to resolve once
+ * the Fumadocs packages are gone.
+ */
+export const stripFumadocsImports = (source: string): string => {
+  const stripped = source.replace(FUMADOCS_IMPORT, "");
+  // Collapse the blank gap a removed import block leaves behind.
+  return stripped === source ? source : stripped.replaceAll(/\n{3,}/gu, "\n\n");
+};
+
+// ---------------------------------------------------------------------------
+// Callouts
+// ---------------------------------------------------------------------------
+
+/** Fumadocs `<Callout type="X">` values mapped to Blume directive names. */
+const CALLOUT_TYPE_DIRECTIVES: Record<string, string> = {
+  error: "danger",
+  info: "info",
+  note: "note",
+  success: "success",
+  tip: "tip",
+  warn: "warning",
+  warning: "warning",
+};
+
+/**
+ * Convert Fumadocs `<Callout type="info|warn|error|…" title="…">` components
+ * into Blume `:::` directives. A bare `<Callout>` becomes `:::note`; the `icon`
+ * prop is dropped.
+ */
+export const rewriteFumadocsCallouts = (source: string): string =>
+  rewriteCallouts(source, {
+    defaultDirective: "note",
+    tagDirectives: {},
+    tags: ["Callout"],
+    typeDirectives: CALLOUT_TYPE_DIRECTIVES,
+  });
+
+// ---------------------------------------------------------------------------
+// Container component renames
+// ---------------------------------------------------------------------------
+
+/**
+ * Rename Fumadocs container components to their Blume equivalents. The
+ * lookahead in `renameTag` means a longer tag (`Accordions`, `Files`) is never
+ * matched by the rule for its shorter prefix (`Accordion`, `File`), so the
+ * item-level renames run first and the container renames second:
+ *
+ * - `<Cards>` -> `<CardGroup>` (items stay `<Card>`).
+ * - `<Accordions>`/`<Accordion>` -> `<Accordion>`/`<AccordionItem>`.
+ * - `<Files>`/`<Folder>`/`<File>` -> `<FileTree>`/`<TreeFolder>`/`<TreeFile>`.
+ */
+export const rewriteFumadocsContainers = (source: string): string => {
+  let out = renameTag(source, "Cards", "CardGroup");
+  out = renameTag(out, "Accordion", "AccordionItem");
+  out = renameTag(out, "Accordions", "Accordion");
+  out = renameTag(out, "File", "TreeFile");
+  out = renameTag(out, "Folder", "TreeFolder");
+  out = renameTag(out, "Files", "FileTree");
+  return out;
+};
+
+// ---------------------------------------------------------------------------
+// Tabs (items + value -> per-Tab title)
+// ---------------------------------------------------------------------------
+
+const TABS_TAG = /<Tabs(?=[\s/>])/u;
+const TAB_TAG = /<Tab(?=[\s/>])/u;
+const ITEM_LITERAL = /'(?<s>[^']*)'|"(?<d>[^"]*)"|`(?<t>[^`]*)`/gu;
+
+const escapeAttribute = (value: string): string =>
+  value.replaceAll('"', "&quot;");
+
+/** Find the close brace matching the `{` at `open`, or -1 if unterminated. */
+const matchBrace = (source: string, open: number): number => {
+  let depth = 0;
+  for (let index = open; index < source.length; index += 1) {
+    if (source[index] === "{") {
+      depth += 1;
+    } else if (source[index] === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return -1;
+};
+
+/** Span of an `items={…}` expression within a tag's attributes, or null. */
+const itemsSpan = (attrs: string): { end: number; start: number } | null => {
+  const match = /\bitems\s*=\s*/u.exec(attrs);
+  if (!match) {
+    return null;
+  }
+  const braceStart = attrs.indexOf("{", match.index + match[0].length);
+  if (braceStart === -1) {
+    return null;
+  }
+  const braceEnd = matchBrace(attrs, braceStart);
+  return braceEnd === -1 ? null : { end: braceEnd, start: match.index };
+};
+
+/** Read the string literals from a Fumadocs `<Tabs items={[…]}>` attribute. */
+const parseItems = (attrs: string): string[] => {
+  const span = itemsSpan(attrs);
+  if (!span) {
+    return [];
+  }
+  const inner = attrs.slice(span.start, span.end + 1);
+  const items: string[] = [];
+  for (const match of inner.matchAll(ITEM_LITERAL)) {
+    items.push(match.groups?.s ?? match.groups?.d ?? match.groups?.t ?? "");
+  }
+  return items;
+};
+
+/** Rebuild a `<Tabs …>` open tag with the `items={…}` attribute removed. */
+const buildTabsOpen = (attrs: string, selfClosing: boolean): string => {
+  const span = itemsSpan(attrs);
+  const withoutItems = span
+    ? attrs.slice(0, span.start) + attrs.slice(span.end + 1)
+    : attrs;
+  const body = withoutItems.replace(/\/\s*$/u, "").trim();
+  const space = body ? ` ${body}` : "";
+  return selfClosing ? `<Tabs${space} />` : `<Tabs${space}>`;
+};
+
+/** Give a single `<Tab …>` open tag a `title`, preferring its own `value`. */
+const titleizeTab = (tag: string, fallback: string | undefined): string => {
+  if (/\btitle\s*=/u.test(tag)) {
+    return tag;
+  }
+  if (/\bvalue\s*=/u.test(tag)) {
+    return tag.replace(/\bvalue(?<eq>\s*=)/u, "title$<eq>");
+  }
+  if (fallback === undefined) {
+    return tag;
+  }
+  return tag.replace(/^<Tab/u, `<Tab title="${escapeAttribute(fallback)}"`);
+};
+
+/**
+ * Find the `</name>` that closes the tag opened at `from` (an index just past
+ * the open tag's `>`), honoring nesting. Returns its start index, or -1.
+ */
+const findMatchingClose = (
+  source: string,
+  from: number,
+  name: string
+): number => {
+  const token = new RegExp(`<${name}(?=[\\s/>])|</${name}>`, "gu");
+  token.lastIndex = from;
+  let depth = 1;
+  for (let match = token.exec(source); match; match = token.exec(source)) {
+    if (match[0].startsWith("</")) {
+      depth -= 1;
+      if (depth === 0) {
+        return match.index;
+      }
+    } else {
+      depth += 1;
+    }
+  }
+  return -1;
+};
+
+/** Title the direct `<Tab>` children of a Tabs block, skipping nested Tabs. */
+const titleizeTabChildren = (inner: string, items: string[]): string => {
+  let output = "";
+  let cursor = 0;
+  let position = 0;
+
+  while (cursor < inner.length) {
+    const rest = inner.slice(cursor);
+    const tab = TAB_TAG.exec(rest);
+    if (!tab) {
+      output += rest;
+      break;
+    }
+    const nested = TABS_TAG.exec(rest);
+    if (nested && nested.index < tab.index) {
+      const start = cursor + nested.index;
+      const openEnd = findOpenTagEnd(inner, start + "<Tabs".length);
+      const close =
+        openEnd === -1 ? -1 : findMatchingClose(inner, openEnd + 1, "Tabs");
+      if (close === -1) {
+        output += inner.slice(cursor);
+        break;
+      }
+      const end = close + "</Tabs>".length;
+      output += inner.slice(cursor, end);
+      cursor = end;
+      continue;
+    }
+    const start = cursor + tab.index;
+    const openEnd = findOpenTagEnd(inner, start + "<Tab".length);
+    if (openEnd === -1) {
+      output += inner.slice(cursor, start + 1);
+      cursor = start + 1;
+      continue;
+    }
+    const tagText = inner.slice(start, openEnd + 1);
+    output +=
+      inner.slice(cursor, start) + titleizeTab(tagText, items[position]);
+    position += 1;
+    cursor = openEnd + 1;
+  }
+
+  return output;
+};
+
+/**
+ * Reshape Fumadocs tabs to Blume's API. Fumadocs declares tab labels on the
+ * parent (`<Tabs items={['npm','pnpm']}>`) and selects with `<Tab value="npm">`;
+ * Blume's `<Tab>` carries its own `title`. Each tab is titled from its `value`
+ * (or the positional `items` entry) and the `items` prop is stripped. Nested
+ * tab groups are handled recursively with their own `items`.
+ */
+export const rewriteFumadocsTabs = (source: string): string => {
+  let output = "";
+  let cursor = 0;
+
+  while (cursor < source.length) {
+    const match = TABS_TAG.exec(source.slice(cursor));
+    if (!match) {
+      output += source.slice(cursor);
+      break;
+    }
+    const start = cursor + match.index;
+    const openEnd = findOpenTagEnd(source, start + "<Tabs".length);
+    if (openEnd === -1) {
+      output += source.slice(cursor, start + 1);
+      cursor = start + 1;
+      continue;
+    }
+    const attrs = source.slice(start + "<Tabs".length, openEnd);
+    const selfClosing = attrs.trimEnd().endsWith("/");
+    output += source.slice(cursor, start);
+
+    if (selfClosing) {
+      output += buildTabsOpen(attrs, true);
+      cursor = openEnd + 1;
+      continue;
+    }
+
+    const close = findMatchingClose(source, openEnd + 1, "Tabs");
+    if (close === -1) {
+      output += source.slice(start, openEnd + 1);
+      cursor = openEnd + 1;
+      continue;
+    }
+    const inner = rewriteFumadocsTabs(source.slice(openEnd + 1, close));
+    output += buildTabsOpen(attrs, false);
+    output += titleizeTabChildren(inner, parseItems(attrs));
+    output += "</Tabs>";
+    cursor = close + "</Tabs>".length;
+  }
+
+  return output;
+};
+
+// ---------------------------------------------------------------------------
+// Includes
+// ---------------------------------------------------------------------------
+
+const INCLUDE = /<include\b[^>]*>(?<path>[\s\S]*?)<\/include>/gu;
+
+interface IncludeOptions {
+  filePath: string;
+  readFile?: (file: string) => Promise<string>;
+  seen?: Set<string>;
+}
+
+/**
+ * Inline Fumadocs `<include>./partial.mdx</include>` references — source-level
+ * includes with no Blume runtime equivalent. The referenced file's frontmatter
+ * is stripped, nested includes are resolved (with a cycle guard), and the path
+ * is resolved relative to the including file. Missing or circular targets are
+ * left untouched and reported.
+ */
+export const inlineFumadocsIncludes = async (
+  source: string,
+  options: IncludeOptions
+): Promise<{ content: string; warnings: string[] }> => {
+  const matches = [...source.matchAll(INCLUDE)];
+  if (matches.length === 0) {
+    return { content: source, warnings: [] };
+  }
+
+  const read = options.readFile ?? ((file) => readFileFromDisk(file, "utf-8"));
+  const seen = options.seen ?? new Set<string>();
+  const warnings: string[] = [];
+  let content = source;
+
+  for (const match of matches) {
+    const rawPath = match.groups?.path?.trim() ?? "";
+    if (!rawPath) {
+      continue;
+    }
+    const target = resolve(dirname(options.filePath), rawPath);
+    if (seen.has(target)) {
+      warnings.push(`Circular <include> "${rawPath}" — left as-is.`);
+      continue;
+    }
+    if (!existsSync(target)) {
+      warnings.push(`<include> target "${rawPath}" not found — left as-is.`);
+      continue;
+    }
+    seen.add(target);
+    // oxlint-disable-next-line no-await-in-loop -- sequential include reads
+    const raw = await read(target);
+    // oxlint-disable-next-line no-await-in-loop -- sequential include reads
+    const nested = await inlineFumadocsIncludes(matter(raw).content.trim(), {
+      ...options,
+      filePath: target,
+      seen,
+    });
+    seen.delete(target);
+    warnings.push(...nested.warnings);
+    content = content.replace(match[0], () => nested.content);
+  }
+
+  return { content, warnings };
+};
+
+// ---------------------------------------------------------------------------
+// Unsupported components
+// ---------------------------------------------------------------------------
+
+/** Fumadocs components with no drop-in Blume equivalent — flagged for review. */
+const UNSUPPORTED_COMPONENTS = [
+  "Banner",
+  "DynamicCodeBlock",
+  "ImageZoom",
+  "InlineTOC",
+];
+
+/** Names of Fumadocs components in `source` that need manual attention. */
+export const unsupportedFumadocsComponents = (source: string): string[] =>
+  UNSUPPORTED_COMPONENTS.filter((name) =>
+    new RegExp(`<${name}\\b`, "u").test(source)
+  );

package/src/migrate/fumadocs/frontmatter.ts

@@ -0,0 +1,18 @@
+import { stripUnknownPageMeta } from "../shared.ts";
+
+/**
+ * Normalize Fumadocs page frontmatter for Blume. Fumadocs' core fields
+ * (`title`, `description`, `icon`) already validate against Blume's page schema
+ * and pass through untouched; Fumadocs-only keys with no equivalent — most
+ * notably `full` (full-width, no-TOC layout) — are dropped by the strict-schema
+ * strip and reported so the author can re-apply them by hand.
+ */
+export const normalizeFumadocsPageMeta = (
+  value: unknown
+): { data: Record<string, unknown>; removed: string[] } => {
+  const data =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? { ...(value as Record<string, unknown>) }
+      : {};
+  return stripUnknownPageMeta(data);
+};