blume 0.1.0 → 0.1.2

package/src/core/tsconfig-aliases.ts

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+import { dirname, isAbsolute, join, resolve } from "pathe";
+
+/**
+ * Read the project's TypeScript path aliases (`compilerOptions.paths`) and turn
+ * them into Vite `resolve.alias` entries, so `@/`-style imports in custom pages,
+ * islands, and components resolve in the generated Astro build exactly as they
+ * do in the user's own tooling.
+ *
+ * The generated `.blume/` runtime is its own Astro project with its own tsconfig
+ * and never inherits the project's, so without this every shadcn-style `@/…`
+ * import would have to be rewritten to a relative path. Reading the aliases here
+ * lets those components port over unchanged.
+ *
+ * Best-effort and non-fatal: tsconfig is parsed leniently (it is JSONC —
+ * comments and trailing commas), a single `extends` chain is followed to the
+ * file that actually declares `paths`, and anything unparseable yields no
+ * aliases (the prior behavior).
+ */
+
+/** Strip `//` line and `/* *\/` block comments that sit outside strings. */
+const stripJsonComments = (text: string): string => {
+  let out = "";
+  let inString = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      out += char;
+      if (char === "\\") {
+        out += text[index + 1] ?? "";
+        index += 1;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      out += char;
+      continue;
+    }
+    if (char === "/" && text[index + 1] === "/") {
+      const newline = text.indexOf("\n", index + 2);
+      index = newline === -1 ? text.length : newline - 1;
+      continue;
+    }
+    if (char === "/" && text[index + 1] === "*") {
+      const end = text.indexOf("*/", index + 2);
+      index = end === -1 ? text.length : end + 1;
+      continue;
+    }
+    out += char;
+  }
+  return out;
+};
+
+const TRAILING_COMMA = /,(?<rest>\s*[}\]])/gu;
+
+/** Parse JSONC (tsconfig) into a plain object, or null if it can't be read. */
+const parseJsonc = (text: string): Record<string, unknown> | null => {
+  try {
+    const cleaned = stripJsonComments(text).replaceAll(
+      TRAILING_COMMA,
+      "$<rest>"
+    );
+    const value: unknown = JSON.parse(cleaned);
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const isFile = (path: string): boolean => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/** Resolve a tsconfig `extends` target (relative path, directory, or package). */
+const resolveExtends = (spec: string, fromDir: string): string | null => {
+  if (spec.startsWith(".") || isAbsolute(spec)) {
+    const candidates = spec.endsWith(".json")
+      ? [resolve(fromDir, spec)]
+      : [
+          resolve(fromDir, `${spec}.json`),
+          resolve(fromDir, spec, "tsconfig.json"),
+          resolve(fromDir, spec),
+        ];
+    return candidates.find(isFile) ?? null;
+  }
+  // A bare specifier points at a package's shared config (e.g. `@tsconfig/*`).
+  try {
+    const require_ = createRequire(pathToFileURL(join(fromDir, "_.js")).href);
+    for (const sub of [`${spec}/tsconfig.json`, spec]) {
+      try {
+        return require_.resolve(sub);
+      } catch {
+        // try the next candidate
+      }
+    }
+  } catch {
+    // createRequire failed; fall through
+  }
+  return null;
+};
+
+interface LoadedPaths {
+  /** Directory `paths` entries resolve against (`dirname(file)` + `baseUrl`). */
+  baseDir: string;
+  paths: Record<string, unknown>;
+}
+
+/** Find the nearest tsconfig in an `extends` chain that declares `paths`. */
+const loadPaths = (file: string, seen: Set<string>): LoadedPaths | null => {
+  if (seen.has(file) || !existsSync(file)) {
+    return null;
+  }
+  seen.add(file);
+  const json = parseJsonc(readFileSync(file, "utf-8"));
+  if (!json) {
+    return null;
+  }
+  const options = (json.compilerOptions ?? {}) as Record<string, unknown>;
+  if (options.paths && typeof options.paths === "object") {
+    const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : ".";
+    return {
+      baseDir: resolve(dirname(file), baseUrl),
+      paths: options.paths as Record<string, unknown>,
+    };
+  }
+  // `extends` is a string or, since TS 5.0, an array searched first-to-last.
+  const bases = Array.isArray(json.extends)
+    ? json.extends
+    : [json.extends].filter(Boolean);
+  for (const base of bases) {
+    if (typeof base !== "string") {
+      continue;
+    }
+    const resolved = resolveExtends(base, dirname(file));
+    const found = resolved ? loadPaths(resolved, seen) : null;
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+};
+
+/** Convert one tsconfig `paths` mapping to a Vite alias, or null to skip. */
+const toAlias = (
+  key: string,
+  value: unknown,
+  baseDir: string
+): { find: string; replacement: string } | null => {
+  // tsconfig allows a fallback array; Vite aliases are 1:1, so take the first.
+  const first = Array.isArray(value) ? value[0] : value;
+  if (typeof first !== "string") {
+    return null;
+  }
+  const find = key.endsWith("/*") ? key.slice(0, -2) : key;
+  const target = first.endsWith("/*") ? first.slice(0, -2) : first;
+  // A bare `*`/`/*` catch-all would alias every import — never wire that.
+  if (find === "" || find === "*") {
+    return null;
+  }
+  return { find, replacement: resolve(baseDir, target) };
+};
+
+/**
+ * Resolve the project's tsconfig/jsconfig path aliases to absolute Vite
+ * `resolve.alias` entries (`find` → absolute replacement). Returns `{}` when no
+ * config or no usable `paths` is found.
+ */
+export const resolveTsconfigAliases = (
+  root: string
+): Record<string, string> => {
+  const entry = ["tsconfig.json", "jsconfig.json"]
+    .map((name) => join(root, name))
+    .find((file) => existsSync(file));
+  if (!entry) {
+    return {};
+  }
+  const loaded = loadPaths(entry, new Set());
+  if (!loaded) {
+    return {};
+  }
+  const aliases: Record<string, string> = {};
+  for (const [key, value] of Object.entries(loaded.paths)) {
+    const alias = toAlias(key, value, loaded.baseDir);
+    if (alias) {
+      aliases[alias.find] = alias.replacement;
+    }
+  }
+  return aliases;
+};

package/src/index.ts

@@ -1,4 +1,15 @@
 export { defineConfig } from "./core/config.ts";
+export type {
+  BlumeBanner,
+  BlumeData,
+  BlumeDataConfig,
+  BlumeDataI18n,
+  BlumeDataLocale,
+  BlumeFavicon,
+  BlumeFeed,
+  BlumeLogo,
+  BlumeRoute,
+} from "./core/data.ts";
 export { defineComponents } from "./core/define-components.ts";
 export type {
   ComponentOverride,
@@ -10,6 +21,7 @@ export type {
   FolderMetaDefinition,
   FolderMetaFactory,
 } from "./core/define-meta.ts";
+export type { UIStrings } from "./core/i18n-ui.ts";
 export type {
   BlumeConfig,
   FolderMeta,

package/src/markdown/index.ts

@@ -6,6 +6,7 @@ import {
   transformerNotationHighlight,
   transformerNotationWordHighlight,
 } from "@shikijs/transformers";
+import { codeToHtml } from "shiki";
 
 import { codeTitleTransformer } from "./code-title.ts";
 import { directiveToCalloutPlugin } from "./directives.ts";
@@ -97,6 +98,74 @@ export const blumeShikiTransformers = (
   return transformers;
 };
 
+/**
+ * The light/dark Shiki themes Blume highlights with. Kept in lockstep with the
+ * generated Astro config's `shikiConfig.themes` so code highlighted outside the
+ * Markdown pipeline (via {@link highlightCode}) matches fenced code exactly.
+ */
+const CODE_THEMES = { dark: "github-dark", light: "github-light" } as const;
+
+const escapeHtml = (value: string): string =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+/**
+ * Tag the highlighted `<pre>` with `astro-code` (plus any extra classes) so the
+ * theme's code-block styles apply — `codeToHtml`'s bare output is `pre.shiki`,
+ * which the theme doesn't style.
+ */
+const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
+  ({
+    name: "blume:astro-code-class",
+    pre(node: { properties: Record<string, unknown> }) {
+      const existing =
+        typeof node.properties.class === "string" ? node.properties.class : "";
+      node.properties.class = `astro-code ${extra ?? ""} ${existing}`
+        .replaceAll(/\s+/gu, " ")
+        .trim();
+    },
+  }) as unknown as ShikiTransformer;
+
+export interface HighlightCodeOptions extends BlumeShikiOptions {
+  /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
+  className?: string;
+}
+
+/**
+ * Highlight a code string with the same Shiki themes and transformers as Blume's
+ * Markdown code fences, returning ready-to-render HTML. Use it to show themed
+ * code *outside* the Markdown pipeline (custom pages, components): the output
+ * carries the `astro-code` class and dual (light/dark) color variables, so the
+ * theme styles it — including the light/dark swap — with no extra CSS. The
+ * theme's code-block rules are scoped to `.prose`, so render the result inside a
+ * `.prose` container (the shipped `<CodeBlock>` does this). An unknown language
+ * falls back to an escaped plain block.
+ */
+export const highlightCode = async (
+  code: string,
+  lang: string,
+  options: HighlightCodeOptions = {}
+): Promise<string> => {
+  try {
+    return await codeToHtml(code, {
+      defaultColor: false,
+      lang,
+      themes: CODE_THEMES,
+      transformers: [
+        ...blumeShikiTransformers({ icons: options.icons }),
+        astroCodeClassTransformer(options.className),
+      ],
+    });
+  } catch {
+    const className = `astro-code ${options.className ?? ""}`
+      .replaceAll(/\s+/gu, " ")
+      .trim();
+    return `<pre class="${className}"><code>${escapeHtml(code)}</code></pre>`;
+  }
+};
+
 /**
  * Sätteri Markdown features Blume enables beyond Astro's defaults. GFM,
  * frontmatter, and smart punctuation are already on; this adds superscript

package/src/migrate/fumadocs/config.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 
-import { join } from "pathe";
+import { basename, dirname, join } from "pathe";
 
 import type { BlumeConfig } from "../../core/schema.ts";
 
@@ -39,6 +39,41 @@ const prettifyTitle = (name: string): string => {
     .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)) {
@@ -48,9 +83,23 @@ const readTitle = async (root: string): Promise<string> => {
     const parsed = JSON.parse(await readFile(packageJson, "utf-8")) as {
       name?: unknown;
     };
-    return typeof parsed.name === "string" && parsed.name.trim()
-      ? prettifyTitle(parsed.name)
-      : "Documentation";
+    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";
   }

package/src/migrate/fumadocs/content.ts

@@ -1,9 +1,9 @@
 import { existsSync } from "node:fs";
 import { readFile as readFileFromDisk } from "node:fs/promises";
 
-import matter from "gray-matter";
 import { dirname, resolve } from "pathe";
 
+import matter from "../../core/frontmatter.ts";
 import { findOpenTagEnd, renameTag, rewriteCallouts } from "../shared.ts";
 
 /**

package/src/migrate/fumadocs/groups.ts

@@ -0,0 +1,230 @@
+import { existsSync, statSync } from "node:fs";
+import { mkdir, rename, writeFile } from "node:fs/promises";
+
+import { basename, join } from "pathe";
+
+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 => {
+  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 };
+};