blume 0.0.0 → 0.1.1

package/src/markdown/language-icon.ts

@@ -0,0 +1,172 @@
+/**
+ * A Shiki transformer that prepends a brand icon to a code block's header,
+ * keyed off the fence language. Icons are sourced from `simple-icons` (raw SVG
+ * path data) at build time and emitted as an inline `<svg>` — no client JS and
+ * no React, so it works in the core theme. The icon renders in `currentColor`
+ * (the muted header color) so it stays legible in both light and dark; brand
+ * hex colors are skipped because dark-on-dark logos (Next.js, Rust…) vanish.
+ *
+ * The theme styles `.blume-lang-icon` and shifts the language label
+ * (`pre[data-icon]::before`) to make room.
+ */
+
+import {
+  siAstro,
+  siC,
+  siCplusplus,
+  siCss3,
+  siDart,
+  siDocker,
+  siGnubash,
+  siGo,
+  siGraphql,
+  siHtml5,
+  siJavascript,
+  siJson,
+  siKotlin,
+  siLess,
+  siLua,
+  siMarkdown,
+  siMdx,
+  siMysql,
+  siNextdotjs,
+  siPhp,
+  siPrisma,
+  siPython,
+  siReact,
+  siRuby,
+  siRust,
+  siSass,
+  siScala,
+  siSvelte,
+  siSvg,
+  siSwift,
+  siToml,
+  siTypescript,
+  siVuedotjs,
+  siWebassembly,
+  siYaml,
+} from "simple-icons";
+
+/** The slice of a `simple-icons` icon Blume reads (the SVG path data). */
+interface SimpleIcon {
+  path: string;
+}
+
+/** Fence language (and common aliases) → icon. Unmapped languages get none. */
+const LANGUAGE_ICONS: Record<string, SimpleIcon> = {
+  astro: siAstro,
+  bash: siGnubash,
+  c: siC,
+  "c++": siCplusplus,
+  cjs: siJavascript,
+  cpp: siCplusplus,
+  css: siCss3,
+  cts: siTypescript,
+  dart: siDart,
+  docker: siDocker,
+  dockerfile: siDocker,
+  go: siGo,
+  gql: siGraphql,
+  graphql: siGraphql,
+  html: siHtml5,
+  javascript: siJavascript,
+  js: siJavascript,
+  json: siJson,
+  json5: siJson,
+  jsonc: siJson,
+  jsx: siReact,
+  kotlin: siKotlin,
+  kt: siKotlin,
+  less: siLess,
+  lua: siLua,
+  markdown: siMarkdown,
+  md: siMarkdown,
+  mdx: siMdx,
+  mjs: siJavascript,
+  mts: siTypescript,
+  nextjs: siNextdotjs,
+  php: siPhp,
+  prisma: siPrisma,
+  py: siPython,
+  python: siPython,
+  rb: siRuby,
+  react: siReact,
+  rs: siRust,
+  ruby: siRuby,
+  rust: siRust,
+  sass: siSass,
+  scala: siScala,
+  scss: siSass,
+  sh: siGnubash,
+  shell: siGnubash,
+  sql: siMysql,
+  svelte: siSvelte,
+  svg: siSvg,
+  swift: siSwift,
+  toml: siToml,
+  ts: siTypescript,
+  tsx: siReact,
+  typescript: siTypescript,
+  vue: siVuedotjs,
+  wasm: siWebassembly,
+  yaml: siYaml,
+  yml: siYaml,
+  zsh: siGnubash,
+};
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** The slice of Shiki's transformer `this` context the icon hook reads. */
+interface IconContext {
+  options: { lang?: string };
+}
+
+/** The `<pre>` hast node a Shiki `pre` hook receives. */
+interface IconPreNode {
+  children: HastNode[];
+  properties: Record<string, boolean | number | string | undefined>;
+}
+
+/** A Shiki-compatible transformer, typed structurally to avoid a Shiki dep. */
+export interface LanguageIconTransformer {
+  name: string;
+  pre: (this: IconContext, node: IconPreNode) => void;
+}
+
+/** Build an inline SVG hast node from a simple-icons path. */
+const iconNode = (path: string): HastNode => ({
+  children: [
+    { children: [], properties: { d: path }, tagName: "path", type: "element" },
+  ],
+  properties: {
+    ariaHidden: "true",
+    className: ["blume-lang-icon"],
+    fill: "currentColor",
+    height: 14,
+    viewBox: "0 0 24 24",
+    width: 14,
+  },
+  tagName: "svg",
+  type: "element",
+});
+
+/** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
+export const languageIconTransformer = (): LanguageIconTransformer => ({
+  name: "blume:language-icon",
+  pre(node) {
+    const icon = LANGUAGE_ICONS[(this.options.lang ?? "").toLowerCase()];
+    if (!icon) {
+      return;
+    }
+    node.children.unshift(iconNode(icon.path));
+    node.properties.dataIcon = "";
+  },
+});

package/src/markdown/math.ts

@@ -0,0 +1,32 @@
+import { jsxAttribute, jsxFlowElement, jsxTextElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+
+interface MathNode extends MdastNode {
+  value: string;
+}
+
+/**
+ * Satteri MDAST plugin that turns math nodes into Blume's `<Math>` component,
+ * which renders them with KaTeX at build time. Block math (`$$…$$`) becomes a
+ * block element; inline math (`$…$`) stays inline. Only active when math is
+ * enabled in config, so `$` is otherwise left as literal text.
+ */
+export const mathPlugin = () => ({
+  inlineMath(node: MathNode, ctx: MdastVisitorContext) {
+    ctx.replaceNode(
+      node,
+      jsxTextElement("Math", [jsxAttribute("code", node.value)])
+    );
+  },
+  math(node: MathNode, ctx: MdastVisitorContext) {
+    ctx.replaceNode(
+      node,
+      jsxFlowElement(
+        "Math",
+        [jsxAttribute("code", node.value), jsxAttribute("display")],
+        []
+      )
+    );
+  },
+  name: "blume-math",
+});

package/src/markdown/mdast.ts

@@ -0,0 +1,48 @@
+/**
+ * Minimal structural types and node builders for the (alpha) Satteri MDAST
+ * plugin API. We model only what Blume's plugins read and construct; the full
+ * types live in `satteri`, a transitive dependency. Plugins are bridged to
+ * Satteri's real `MdastPlugin` type at a single boundary in `index.ts`.
+ */
+
+/** The visitor context Blume's plugins use to mutate the tree. */
+export interface MdastVisitorContext {
+  replaceNode: (node: unknown, replacement: unknown) => void;
+}
+
+/** Any MDAST node, keyed loosely since we build a small subset by hand. */
+export interface MdastNode {
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Build an MDX JSX attribute. A `null` value renders as a boolean attribute. */
+export const jsxAttribute = (name: string, value: string | null = null) => ({
+  name,
+  type: "mdxJsxAttribute",
+  value,
+});
+
+type JsxAttribute = ReturnType<typeof jsxAttribute>;
+
+/** Build a block-level MDX JSX element (`<Name>…</Name>`). */
+export const jsxFlowElement = (
+  name: string,
+  attributes: JsxAttribute[],
+  children: unknown[]
+) => ({ attributes, children, name, type: "mdxJsxFlowElement" });
+
+/** Build an inline MDX JSX element (phrasing context). */
+export const jsxTextElement = (
+  name: string,
+  attributes: JsxAttribute[],
+  children: unknown[] = []
+) => ({ attributes, children, name, type: "mdxJsxTextElement" });
+
+/** Build a fenced code block node. */
+export const codeBlock = (lang: string, value: string) => ({
+  lang,
+  meta: null,
+  type: "code",
+  value,
+});

package/src/markdown/mermaid.ts

@@ -0,0 +1,37 @@
+import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+
+interface CodeNode extends MdastNode {
+  lang?: string | null;
+  value: string;
+}
+
+/**
+ * Satteri MDAST plugin that turns a ` ```mermaid ` code block into a
+ * `<blume-mermaid>` custom element carrying the raw diagram source. There is no
+ * importable component — the fence is the whole interface. The element is
+ * rendered on the client (Mermaid needs a DOM), so the source rides on a string
+ * attribute rather than as child text (which MDX would try to parse).
+ */
+export const mermaidPlugin = () => ({
+  code(node: CodeNode, ctx: MdastVisitorContext) {
+    if (node.lang !== "mermaid") {
+      return;
+    }
+    ctx.replaceNode(
+      node,
+      jsxFlowElement(
+        "blume-mermaid",
+        [
+          jsxAttribute(
+            "class",
+            "not-prose my-6 flex justify-center overflow-x-auto"
+          ),
+          jsxAttribute("data-source", node.value),
+        ],
+        []
+      )
+    );
+  },
+  name: "blume-mermaid",
+});

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,155 @@
+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 };
+};