@suzumiyaaoba/mdxr 0.1.0

package/src/render.ts

@@ -0,0 +1,337 @@
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { createElement } from "react";
+
+import { clientJs } from "./client-js.js";
+import { mergeUserComponents } from "./component-map.js";
+import type { ResolvedConfig } from "./config.js";
+import { loadConfig } from "./config.js";
+import type { ComponentMap } from "./define.js";
+import { formatError } from "./format-error.js";
+import { nonEmpty } from "./guards.js";
+import { htmlDocument } from "./html.js";
+import { buildHydrateScript } from "./hydrate.js";
+import { loadUserModule, resolveModuleEntry } from "./load-user-module.js";
+import { mdxToHtml } from "./mdx.js";
+import { pkgRoot } from "./paths.js";
+import type { CssSource } from "./tailwind.js";
+import { buildCss } from "./tailwind.js";
+import { builtinComponents } from "./ui/index.js";
+import { PlanHeader } from "./ui/plan.js";
+import { isStatus, STATUSES } from "./ui/status-badge.js";
+
+export interface LoadedComponents {
+  components: ComponentMap;
+  code?: string;
+}
+
+/** Load a user components module (file or directory with an index file). */
+export const loadComponents = async (
+  componentsPath: string
+): Promise<LoadedComponents> => {
+  const entry = resolveModuleEntry(componentsPath);
+  const { module: mod, code } = await loadUserModule(entry);
+  return { code, components: mergeUserComponents(mod) };
+};
+
+/** Components named by `config.componentsPath` — an empty map when unset. */
+export const loadUserComponents = async (
+  config: ResolvedConfig
+): Promise<LoadedComponents> =>
+  config.componentsPath === undefined
+    ? { components: {} }
+    : await loadComponents(config.componentsPath);
+
+/** Read all of our own shipped JS so Tailwind can scan built-in classes.
+ *  Memoized: package sources don't change within a process (serve rebuilds
+ *  would otherwise rescan dist+src on every keystroke). */
+let ownSourcesCache: CssSource[] | undefined;
+const ownSources = async (): Promise<CssSource[]> => {
+  if (ownSourcesCache !== undefined) {
+    return ownSourcesCache;
+  }
+  const dirs = [path.join(pkgRoot, "dist"), path.join(pkgRoot, "src")];
+  const out: CssSource[] = [];
+  const walk = async (d: string): Promise<void> => {
+    const ents = await readdir(d, { withFileTypes: true });
+    await Promise.all(
+      ents.map(async (e) => {
+        const p = path.join(d, e.name);
+        if (e.isDirectory()) {
+          await walk(p);
+        } else if (/\.(?:js|ts|tsx)$/u.test(e.name)) {
+          out.push({
+            content: await readFile(p, "utf-8"),
+            extension: e.name.split(".").pop() ?? "",
+          });
+        }
+      })
+    );
+  };
+  await Promise.all(dirs.filter((d) => existsSync(d)).map(walk));
+  ownSourcesCache = out;
+  return out;
+};
+
+export interface RenderOptions {
+  liveReload?: boolean;
+  /**
+   * Inline a client bundle that hydrates the document (`hydrateRoot`), making
+   * interactive components (Tabs, Accordion, Switch, …) actually work.
+   * Default true; `false` emits purely static HTML.
+   */
+  hydrate?: boolean;
+  /**
+   * Files the render pulled in (theme CSS and its imports) — `mdxr serve`
+   * registers them as extra watch targets so edits outside the document's
+   * own directory still trigger a rebuild.
+   */
+  onDependencies?: (paths: string[]) => void;
+}
+
+export interface RenderSourceOptions extends RenderOptions {
+  /**
+   * Project directory: where `mdxr.config.ts` is looked up and where relative
+   * paths (e.g. `<CodeFile path="…">`) resolve. Defaults to the cwd.
+   */
+  dir?: string;
+  /**
+   * Document path used in error messages and as the base for relative paths.
+   * Defaults to `<dir>/document.mdx`.
+   */
+  filePath?: string;
+}
+
+/**
+ * Inline client bundle for hydration. No catalog component was read → nothing
+ * in the document can hydrate, so the bundle is skipped entirely (pure
+ * markdown docs stay lean). A bundle failure degrades to the (correct)
+ * static output with a warning.
+ */
+const buildHydrateBundle = async (args: {
+  code: string;
+  config: ResolvedConfig;
+  fileLinks: Record<string, string>;
+  headerProps?: Record<string, string | undefined>;
+  hydrate?: boolean;
+  now: string;
+  usedComponents: string[];
+  usedIcons: string[];
+}): Promise<string | undefined> => {
+  if (!(args.hydrate ?? true) || args.usedComponents.length === 0) {
+    return undefined;
+  }
+  try {
+    return await buildHydrateScript({
+      code: args.code,
+      componentsPath:
+        args.config.componentsPath === undefined
+          ? undefined
+          : resolveModuleEntry(args.config.componentsPath),
+      fileLinks: args.fileLinks,
+      header: args.headerProps,
+      now: args.now,
+      usedComponents: args.usedComponents,
+      usedIcons: args.usedIcons,
+    });
+  } catch (error) {
+    process.stderr.write(
+      `mdxr: hydration bundle skipped: ${formatError(error)}\n`
+    );
+    return undefined;
+  }
+};
+
+/**
+ * Frontmatter `status` is free-form YAML, not a JSX prop — normalize case
+ * ("Doing" → "doing") and warn+drop anything outside STATUSES so a metadata
+ * typo can't take down the whole document render.
+ */
+const headerStatus = (raw: string | undefined): string | undefined => {
+  if (raw === undefined) {
+    return undefined;
+  }
+  const norm = raw.trim().toLowerCase();
+  if (isStatus(norm)) {
+    return norm;
+  }
+  process.stderr.write(
+    `mdxr: warning: frontmatter status "${raw}" is not one of ${STATUSES.join("|")} — the badge is skipped\n`
+  );
+  return undefined;
+};
+
+/**
+ * PlanHeader props from frontmatter — present only with a `title` and no
+ * `<Plan>`-style `<article>` root in the body (that would render a second
+ * header). Used for both the SSR header and the hydration payload.
+ */
+const frontmatterHeader = (
+  fm: (key: string) => string | undefined,
+  body: string
+): Record<string, string | undefined> | undefined => {
+  const title = fm("title");
+  if (title === undefined || title === "" || /<article/u.test(body)) {
+    return undefined;
+  }
+  return {
+    date: fm("date"),
+    owner: fm("owner"),
+    status: headerStatus(fm("status")),
+    title,
+    updated: fm("updated"),
+    version: fm("version"),
+  };
+};
+
+/** Render MDX source text to a standalone HTML document. */
+export const render = async (
+  source: string,
+  opts: RenderSourceOptions = {}
+): Promise<string> => {
+  const dir = path.resolve(opts.dir ?? process.cwd());
+  // Relative filePaths anchor to `dir`, not cwd — mdxToHtml resolves
+  // `<CodeFile>`/`file:` links against file.dirname, and `dir` is the
+  // documented base for those (e.g. `mdxr < doc.mdx` with -d).
+  const filePath = path.resolve(dir, opts.filePath ?? "document.mdx");
+  const config: ResolvedConfig = await loadConfig(dir);
+
+  const user = await loadUserComponents(config);
+
+  // hasOwn, not `in`: prototype names ("toString", "constructor") are not
+  // catalog collisions.
+  const collisions = Object.keys(user.components).filter((k) =>
+    Object.hasOwn(builtinComponents, k)
+  );
+  for (const k of collisions) {
+    process.stderr.write(
+      `mdxr: project component <${k}> overrides the built-in\n`
+    );
+  }
+
+  const components: ComponentMap = {
+    ...builtinComponents,
+    ...user.components,
+  };
+
+  const {
+    body,
+    code,
+    fileLinks,
+    frontmatter,
+    renderedAt,
+    renderWithHeader,
+    usedComponents,
+    usedIcons,
+  } = await mdxToHtml(source, components, filePath, {
+    editor: config.editor,
+    hydrate: opts.hydrate,
+  });
+
+  const fmStr = (key: string): string | undefined => {
+    const val: unknown = frontmatter[key];
+    if (typeof val === "string") {
+      return val === "" ? undefined : val;
+    }
+    // YAML parses `date: 2026-09-16` into a Date.
+    if (val instanceof Date) {
+      return val.toISOString().slice(0, 10);
+    }
+    return typeof val === "number" ? String(val) : undefined;
+  };
+
+  const fmTitle = fmStr("title");
+  // `<h1>` may hold inline elements — take the full inner HTML, drop the
+  // tags, and undo the entities React emitted (escapeHtml re-encodes).
+  const h1Text = /<h1[^>]*>(?<text>[\s\S]*?)<\/h1>/u
+    .exec(body)
+    ?.groups?.text.replaceAll(/<[^>]*>/gu, "")
+    .replaceAll("&#x27;", "'")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&amp;", "&")
+    .trim();
+  const title =
+    fmTitle ?? (nonEmpty(h1Text) ? h1Text : undefined) ?? "mdxr document";
+
+  const headerProps = frontmatterHeader(fmStr, body);
+  // The header must be part of the body's vnode tree, not concatenated HTML:
+  // the hydration client mounts Provider > Fragment > [header|null, doc] and
+  // useId() encodes tree position — separately rendered markup would shift
+  // every id/name/htmlFor hydration compares.
+  let docBody = body;
+  let docFileLinks = fileLinks;
+  let docIcons = usedIcons;
+  if (headerProps !== undefined) {
+    const pass = renderWithHeader(createElement(PlanHeader, headerProps));
+    docBody = pass.html;
+    docFileLinks = pass.fileLinks;
+    docIcons = pass.usedIcons;
+  }
+
+  // Read once for the candidate scan; the build imports the theme by path so
+  // relative `@import`s inside it resolve against the theme's own directory.
+  const themeCss =
+    config.themePath === undefined
+      ? undefined
+      : await readFile(config.themePath, "utf-8");
+
+  // Every class that made it into the rendered output is a candidate;
+  // scanning the body covers both built-in and user components.
+  const sources: CssSource[] = [
+    { content: docBody, extension: "html" },
+    { content: source, extension: "mdx" },
+    { content: themeCss ?? "", extension: "css" },
+    ...(await ownSources()),
+    ...(user.code === undefined
+      ? []
+      : [{ content: user.code, extension: "js" }]),
+    ...(config.componentsCode === undefined
+      ? []
+      : [{ content: config.componentsCode, extension: "js" }]),
+  ];
+  const { css, dependencies } = await buildCss(sources, config.themePath);
+  opts.onDependencies?.(dependencies);
+
+  const [js, hydrateJs] = await Promise.all([
+    clientJs(),
+    buildHydrateBundle({
+      code,
+      config,
+      fileLinks: docFileLinks,
+      headerProps,
+      hydrate: opts.hydrate,
+      now: renderedAt,
+      usedComponents,
+      usedIcons: docIcons,
+    }),
+  ]);
+
+  return htmlDocument({
+    body: docBody,
+    clientJs: js,
+    css,
+    hydrateJs,
+    liveReload: opts.liveReload,
+    needsKatex: /class="[^"]*katex/u.test(docBody),
+    needsMermaid: /class="[^"]*mermaid/u.test(docBody),
+    title,
+  });
+};
+
+/** Read `mdxPath` and render it to a standalone HTML document. */
+export const renderFile = async (
+  mdxPath: string,
+  opts: RenderOptions = {}
+): Promise<string> => {
+  const abs = path.resolve(mdxPath);
+  const source = await readFile(abs, "utf-8");
+  return await render(source, {
+    ...opts,
+    dir: path.dirname(abs),
+    filePath: abs,
+  });
+};

package/src/serve.ts

@@ -0,0 +1,322 @@
+import { once } from "node:events";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+
+import { formatError } from "./format-error.js";
+import type { RenderSourceOptions } from "./render.js";
+import { render, renderFile } from "./render.js";
+
+const errorPage = (err: unknown): string =>
+  `<!doctype html><meta charset="utf-8"><body style="font-family:monospace;background:#1c1917;color:#fca5a5;padding:2rem"><h1>mdxr render error</h1><pre>${formatError(err).replaceAll("&", "&amp;").replaceAll("<", "&lt;")}</pre></body>`;
+
+interface PreviewTarget {
+  /** Label shown in the startup log. */
+  label: string;
+  /** Re-render the document; errors are served as an error page. */
+  renderDoc: () => Promise<string>;
+  /** Dependency files the last render pulled in (theme CSS + its imports). */
+  deps?: () => string[];
+  /** Directory watched for changes (config, components, theme, sources). */
+  watchDir: string;
+  /** Non-recursive fallback watch target (the document file). */
+  watchFile?: string;
+}
+
+/** Dependency/build output dirs — never worth a watch fd. */
+const SKIP_DIRS = new Set([
+  ".git",
+  ".mdxr-cache",
+  "dist",
+  "node_modules",
+  "storybook-static",
+]);
+
+/**
+ * The set of directories being watched. `fs.watch` recursive mode exists only
+ * on darwin/win32 — elsewhere `arm` puts one non-recursive watcher per
+ * directory, which also survives atomic saves (rename-over kills a watch
+ * aimed at the file itself).
+ */
+const createWatchSet = () => {
+  const watchers: fs.FSWatcher[] = [];
+  const armed = new Set<string>();
+
+  const track = (w: fs.FSWatcher, dir?: string): void => {
+    watchers.push(w);
+    if (dir !== undefined) {
+      armed.add(dir);
+      // A deleted dir kills its watcher — un-arm on close so a recreated
+      // dir is picked up again by the next event's re-scan.
+      w.on("close", () => {
+        armed.delete(dir);
+      });
+    }
+    w.on("error", () => {
+      w.close();
+    });
+  };
+
+  /** One watcher on `dir` itself (no descent). */
+  const armFlat = (dir: string, onEvent: () => void): void => {
+    if (armed.has(dir) || SKIP_DIRS.has(path.basename(dir))) {
+      return;
+    }
+    try {
+      track(fs.watch(dir, onEvent), dir);
+    } catch {
+      // Directory gone or unwatched — skip.
+    }
+  };
+
+  /**
+   * Recursive fallback: a watcher on `dir` plus every directory under it.
+   * The `armed` check guards only the watcher install — the descent still
+   * runs on an already-armed root, so directories created mid-session get
+   * picked up on the next rebuild (armDeps re-arms the tree for this).
+   */
+  const arm = (dir: string, onEvent: () => void): void => {
+    if (SKIP_DIRS.has(path.basename(dir))) {
+      return;
+    }
+    if (!armed.has(dir)) {
+      try {
+        track(fs.watch(dir, onEvent), dir);
+      } catch {
+        // Watch failed (dir gone, fd limit) — children may still be
+        // watchable, so keep descending.
+      }
+    }
+    let ents: fs.Dirent[];
+    try {
+      ents = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of ents) {
+      if (e.isDirectory()) {
+        arm(path.join(dir, e.name), onEvent);
+      }
+    }
+  };
+
+  return {
+    arm,
+    armFlat,
+    close(): void {
+      for (const w of watchers) {
+        w.close();
+      }
+    },
+    get size(): number {
+      return watchers.length;
+    },
+    track,
+  };
+};
+
+const servePreview = async (
+  target: PreviewTarget,
+  port: number
+): Promise<http.Server> => {
+  let html = "";
+  const clients = new Set<http.ServerResponse>();
+  const server = http.createServer((req, res) => {
+    if (req.url === "/__mdxr_events") {
+      res.writeHead(200, {
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+        "content-type": "text/event-stream",
+      });
+      res.write("retry: 1000\n\n");
+      clients.add(res);
+      req.on("close", () => {
+        clients.delete(res);
+      });
+      res.on("error", () => {
+        clients.delete(res);
+      });
+      return;
+    }
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(html);
+  });
+
+  const watch = createWatchSet();
+  let recursiveWatch = false;
+  let timer: NodeJS.Timeout | undefined;
+
+  /**
+   * Dependency files (theme CSS, its nested imports) may live outside the
+   * watched document directory. Inside the watch dir the root watcher covers
+   * them; outside, a flat watcher on the file's own directory suffices —
+   * and avoids descending into a potentially huge ancestor tree. Also
+   * re-arms the tree so directories created mid-session are picked up.
+   */
+  const armDeps = (onEvent: () => void): void => {
+    if (!recursiveWatch) {
+      watch.arm(target.watchDir, onEvent);
+    }
+    for (const dep of target.deps?.() ?? []) {
+      const dir = path.dirname(dep);
+      const inside =
+        dir === target.watchDir ||
+        dir.startsWith(`${target.watchDir}${path.sep}`);
+      if (inside || dir.split(path.sep).includes("node_modules")) {
+        continue;
+      }
+      watch.armFlat(dir, onEvent);
+    }
+  };
+
+  const rebuild = async (onEvent: () => void): Promise<void> => {
+    try {
+      html = await target.renderDoc();
+    } catch (error) {
+      html = errorPage(error);
+    }
+    armDeps(onEvent);
+  };
+
+  // Rebuilds chain onto each other: a change burst during a slow rebuild
+  // can't interleave two renders or serve an older result last. Every link
+  // swallows its own errors, so the stored tail can never reject — nothing
+  // awaits it, and an unhandled rejection would take the server down.
+  let reloading: Promise<void> = Promise.resolve();
+  const reload = (onEvent: () => void): void => {
+    const prev = reloading;
+    reloading = (async () => {
+      await prev;
+      try {
+        await rebuild(onEvent);
+        for (const c of clients) {
+          try {
+            c.write("event: reload\ndata: {}\n\n");
+          } catch {
+            clients.delete(c);
+          }
+        }
+      } catch {
+        // Notified clients are best-effort; rebuild failures are already
+        // rendered into the error page by rebuild() itself.
+      }
+    })();
+  };
+
+  const notify = (): void => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      reload(notify);
+    }, 80);
+  };
+
+  // fs.watch recursive mode exists only on darwin/win32; elsewhere `arm`
+  // installs the per-directory fallback.
+  try {
+    watch.track(fs.watch(target.watchDir, { recursive: true }, notify));
+    recursiveWatch = true;
+  } catch {
+    watch.arm(target.watchDir, notify);
+  }
+  if (watch.size === 0 && target.watchFile !== undefined) {
+    try {
+      watch.track(fs.watch(target.watchFile, notify));
+    } catch {
+      // Live reload just won't fire; the server still serves the document.
+    }
+  }
+  server.on("close", () => {
+    clearTimeout(timer);
+    watch.close();
+  });
+
+  await rebuild(notify);
+
+  // Bind loopback only — the startup log says localhost, and a preview
+  // server has no auth: listening on 0.0.0.0 would expose the document
+  // (and its file links) to the LAN.
+  server.listen(port, "127.0.0.1");
+  try {
+    // Rejects on 'error' (e.g. EADDRINUSE) before 'listening'.
+    await once(server, "listening");
+  } catch (error) {
+    // Close fires the 'close' handler above — without it a failed listen
+    // would leave the watchers armed and keep the process alive.
+    server.close();
+    throw error;
+  }
+
+  const address = server.address();
+  const boundPort =
+    typeof address === "object" && address !== null ? address.port : port;
+  console.log(`mdxr: serving ${target.label} at http://localhost:${boundPort}`);
+  console.log("mdxr: watching for changes (Ctrl+C to stop)");
+  return server;
+};
+
+/**
+ * Wraps a render fn with dependency tracking: `deps` reads the paths the
+ * last render reported via `onDependencies` (theme CSS + its imports), so
+ * `armDeps` can watch files outside the document's own directory.
+ */
+const trackDeps = (
+  renderDoc: (onDeps: (paths: string[]) => void) => Promise<string>
+): Pick<PreviewTarget, "deps" | "renderDoc"> => {
+  let deps: string[] = [];
+  return {
+    deps: () => deps,
+    renderDoc: async () => {
+      const collected: string[] = [];
+      const doc = await renderDoc((d) => {
+        collected.push(...d);
+      });
+      deps = collected;
+      return doc;
+    },
+  };
+};
+
+/** Serve an .mdx file, rebuilding + live-reloading on changes in its directory. */
+export const serve = async (
+  mdxPath: string,
+  port: number
+): Promise<http.Server> => {
+  const abs = path.resolve(mdxPath);
+  return await servePreview(
+    {
+      label: mdxPath,
+      ...trackDeps(
+        async (onDeps) =>
+          await renderFile(abs, { liveReload: true, onDependencies: onDeps })
+      ),
+      watchDir: path.dirname(abs),
+      watchFile: abs,
+    },
+    port
+  );
+};
+
+/** Serve MDX source passed directly (e.g. piped via stdin). */
+export const serveSource = async (
+  source: string,
+  port: number,
+  opts: Omit<RenderSourceOptions, "liveReload" | "onDependencies"> = {}
+): Promise<http.Server> => {
+  const dir = path.resolve(opts.dir ?? process.cwd());
+  return await servePreview(
+    {
+      label: opts.filePath ?? "stdin",
+      ...trackDeps(
+        async (onDeps) =>
+          await render(source, {
+            dir,
+            filePath: opts.filePath,
+            liveReload: true,
+            onDependencies: onDeps,
+          })
+      ),
+      watchDir: dir,
+    },
+    port
+  );
+};