@sorane/core 0.2.0

package/src/diagrams/diagram-meta.ts

@@ -0,0 +1,74 @@
+import type { Root } from "mdast";
+import { visit } from "unist-util-visit";
+import type { DiagramsConfig } from "../config.ts";
+import { buildMermaidHead } from "./mermaid-head.ts";
+import { isGraphvizLang } from "./compile-graphviz.ts";
+
+export interface DiagramRenderMeta {
+  readonly mermaid: number;
+  readonly d2: number;
+  readonly graphviz: number;
+}
+
+export function emptyDiagramMeta(): DiagramRenderMeta {
+  return { mermaid: 0, d2: 0, graphviz: 0 };
+}
+
+export function mergeDiagramMeta(
+  a: DiagramRenderMeta,
+  b: DiagramRenderMeta,
+): DiagramRenderMeta {
+  return {
+    mermaid: a.mermaid + b.mermaid,
+    d2: a.d2 + b.d2,
+    graphviz: a.graphviz + b.graphviz,
+  };
+}
+
+export function countDiagramsForConfig(
+  tree: Root,
+  config: DiagramsConfig,
+): DiagramRenderMeta {
+  let mermaid = 0;
+  let d2 = 0;
+  let graphviz = 0;
+  if (config.enabled === false) return { mermaid, d2, graphviz };
+  visit(tree, "code", (node) => {
+    if (node.lang === "mermaid" && resolveMermaidMode(config) !== "off") {
+      mermaid += 1;
+    } else if (node.lang === "d2" && config.d2?.enabled === true) {
+      d2 += 1;
+    } else if (isGraphvizLang(node.lang) && config.graphviz?.enabled === true) {
+      graphviz += 1;
+    }
+  });
+  return { mermaid, d2, graphviz };
+}
+
+export type MermaidRenderMode = "client" | "build" | "off";
+
+export function resolveMermaidMode(config: DiagramsConfig): MermaidRenderMode {
+  if (config.enabled === false) return "off";
+  const mode = config.mermaid?.mode ?? "client";
+  if (mode === "off") return "off";
+  if (mode === "build") return "build";
+  return "client";
+}
+
+export function diagramHeadForPage(
+  meta: DiagramRenderMeta,
+  rootPrefix: string,
+  config: DiagramsConfig,
+): string | undefined {
+  if (config.enabled === false) return undefined;
+  if (meta.mermaid === 0) return undefined;
+  if (resolveMermaidMode(config) !== "client") return undefined;
+  return buildMermaidHead(rootPrefix);
+}
+
+export function contentNeedsMermaidClient(
+  hasMermaidFences: boolean,
+  config: DiagramsConfig,
+): boolean {
+  return hasMermaidFences && resolveMermaidMode(config) === "client";
+}

package/src/diagrams/emit-diagram-assets.ts

@@ -0,0 +1,135 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import type { DiagramsConfig } from "../config.ts";
+import { resolveThemeAssetDir } from "../theme-assets.ts";
+import { contentNeedsMermaidClient, resolveMermaidMode } from "./diagram-meta.ts";
+
+const require = createRequire(import.meta.url);
+
+export interface EmitDiagramAssetsOptions {
+  readonly cwd: string;
+  readonly outDir: string;
+  readonly config: DiagramsConfig;
+  readonly contentHasMermaid?: boolean;
+  readonly onProgress?: (message: string) => void;
+}
+
+export interface EmitDiagramAssetsResult {
+  readonly copied: boolean;
+  readonly bytes: number;
+  readonly version?: string;
+}
+
+export function substituteMermaidVersion(source: string, version: string): string {
+  return source.replace(/\{\{\s*MERMAID_VERSION\s*\}\}/g, version);
+}
+
+function resolveMermaidPackageRoot(): string | null {
+  try {
+    const pkgPath = require.resolve("mermaid/package.json");
+    return dirname(pkgPath);
+  } catch {
+    return null;
+  }
+}
+
+function listMermaidDistFiles(distDir: string): string[] {
+  const out: string[] = [];
+  const visit = (dir: string): void => {
+    for (const entry of readdirSync(dir)) {
+      const p = join(dir, entry);
+      const s = statSync(p);
+      if (s.isDirectory()) {
+        visit(p);
+        continue;
+      }
+      if (entry.endsWith(".map") || entry.endsWith(".d.ts")) continue;
+      if (entry.endsWith(".mjs") || entry.endsWith(".js")) out.push(p);
+    }
+  };
+  visit(distDir);
+  return out;
+}
+
+export function emitDiagramAssets(opts: EmitDiagramAssetsOptions): EmitDiagramAssetsResult {
+  const log = opts.onProgress ?? (() => {});
+  const config = opts.config;
+
+  if (config.enabled === false) {
+    return { copied: false, bytes: 0 };
+  }
+  if (resolveMermaidMode(config) === "off") {
+    return { copied: false, bytes: 0 };
+  }
+  if (!contentNeedsMermaidClient(opts.contentHasMermaid === true, config)) {
+    log("diagrams: no client mermaid needed; skipping asset copy");
+    return { copied: false, bytes: 0 };
+  }
+
+  const mermaidRoot = resolveMermaidPackageRoot();
+  if (!mermaidRoot) {
+    log("diagrams: mermaid package not found; skipping asset copy");
+    return { copied: false, bytes: 0 };
+  }
+
+  const version = JSON.parse(
+    readFileSync(join(mermaidRoot, "package.json"), "utf8"),
+  ).version as string;
+  const distDir = join(mermaidRoot, "dist");
+  if (!existsSync(distDir)) {
+    log(`diagrams: mermaid dist not found at ${distDir}`);
+    return { copied: false, bytes: 0 };
+  }
+
+  const assetsOut = join(opts.outDir, "assets", "diagrams");
+  const mermaidOut = join(assetsOut, `mermaid-${version}`);
+  mkdirSync(mermaidOut, { recursive: true });
+
+  let bytes = 0;
+  for (const src of listMermaidDistFiles(distDir)) {
+    const rel = relative(distDir, src);
+    const dest = join(mermaidOut, rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+    bytes += statSync(dest).size;
+  }
+
+  const loaderTemplate =
+    resolveThemeAssetDir(opts.cwd, "diagrams") ??
+    resolve(
+      dirname(fileURLToPath(import.meta.url)),
+      "../../../../templates/default/assets/diagrams",
+    );
+  const loaderSrc = join(loaderTemplate, "sorane-mermaid-loader.mjs");
+  if (existsSync(loaderSrc)) {
+    const loaderBody = substituteMermaidVersion(
+      readFileSync(loaderSrc, "utf8"),
+      version,
+    );
+    writeFileSync(join(assetsOut, "sorane-mermaid-loader.mjs"), loaderBody, "utf8");
+    bytes += Buffer.byteLength(loaderBody, "utf8");
+  }
+
+  log(`diagrams: copied mermaid ${version} (${(bytes / 1024).toFixed(1)} KB)`);
+  return { copied: true, bytes, version };
+}
+
+const MERMAID_FENCE_RE = /```mermaid\b/m;
+
+export function contentHasMermaidFences(mdFiles: readonly string[]): boolean {
+  for (const abs of mdFiles) {
+    const text = readFileSync(abs, "utf8");
+    if (MERMAID_FENCE_RE.test(text)) return true;
+  }
+  return false;
+}

package/src/diagrams/mermaid-head.ts

@@ -0,0 +1,6 @@
+import { escapeHtml } from "../render.ts";
+
+export function buildMermaidHead(rootPrefix: string): string {
+  const src = `${rootPrefix}assets/diagrams/sorane-mermaid-loader.mjs`;
+  return `<script type="module" src="${escapeHtml(src)}"></script>`;
+}

package/src/diagrams/needs-async-compile.ts

@@ -0,0 +1,12 @@
+import type { DiagramsConfig } from "../config.ts";
+import { isD2CompileEnabled } from "./compile-d2.ts";
+import { isGraphvizCompileEnabled } from "./compile-graphviz.ts";
+import { isMermaidBuildEnabled } from "./compile-mermaid.ts";
+
+export function needsAsyncDiagramCompile(config?: DiagramsConfig): boolean {
+  return (
+    isD2CompileEnabled(config) ||
+    isMermaidBuildEnabled(config) ||
+    isGraphvizCompileEnabled(config)
+  );
+}

package/src/diagrams/parse-diagram-fence.ts

@@ -0,0 +1,109 @@
+import type { Code, Root } from "mdast";
+import type { Plugin } from "unified";
+import { visit } from "unist-util-visit";
+import type { DiagramsConfig } from "../config.ts";
+import { isGraphvizLang } from "./compile-graphviz.ts";
+
+export type MermaidKind =
+  | "flowchart"
+  | "sequenceDiagram"
+  | "stateDiagram"
+  | "erDiagram"
+  | "gantt"
+  | "pie"
+  | "classDiagram";
+
+export type MermaidKindOrUnsupported = MermaidKind | "unsupported";
+
+const ALT_DOUBLE = /\balt="((?:[^"\\]|\\.)*)"/;
+const ALT_SINGLE = /\balt='((?:[^'\\]|\\.)*)'/;
+
+export function parseInfoString(meta: string | null | undefined): { alt?: string } {
+  if (meta === null || meta === undefined) return {};
+  const m = ALT_DOUBLE.exec(meta) ?? ALT_SINGLE.exec(meta);
+  if (m === null) return {};
+  const value = m[1] ?? "";
+  if (value.length === 0) return {};
+  return { alt: value };
+}
+
+const ALT_COMMENT = /^\s*%%\s*alt\s*:\s*(.+?)\s*$/m;
+
+export function parseAltComment(source: string): string | undefined {
+  const m = ALT_COMMENT.exec(source);
+  if (m === null) return undefined;
+  const value = m[1]!.trim();
+  return value.length > 0 ? value : undefined;
+}
+
+export function detectDiagramKind(source: string): MermaidKindOrUnsupported {
+  for (const rawLine of source.split("\n")) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    if (line.startsWith("%%")) continue;
+    if (line.startsWith("flowchart") || line.startsWith("graph")) return "flowchart";
+    if (line.startsWith("sequenceDiagram")) return "sequenceDiagram";
+    if (line.startsWith("stateDiagram")) return "stateDiagram";
+    if (line.startsWith("erDiagram")) return "erDiagram";
+    if (line.startsWith("gantt")) return "gantt";
+    if (line.startsWith("pie")) return "pie";
+    if (line.startsWith("classDiagram")) return "classDiagram";
+    return "unsupported";
+  }
+  return "unsupported";
+}
+
+export function extractAltText(
+  meta: string | null | undefined,
+  source: string,
+): string | undefined {
+  return parseInfoString(meta).alt ?? parseAltComment(source);
+}
+
+export interface SoraneDiagramMeta {
+  readonly lang: "mermaid" | "d2" | "graphviz";
+  readonly altText?: string;
+  readonly kind?: MermaidKindOrUnsupported | "d2" | "graphviz";
+}
+
+function annotateDiagramCode(
+  node: Code,
+  lang: "mermaid" | "d2" | "graphviz",
+): void {
+  const altText = extractAltText(node.meta, node.value);
+  const kind =
+    lang === "mermaid"
+      ? detectDiagramKind(node.value)
+      : lang === "d2"
+        ? "d2"
+        : "graphviz";
+  const data = (node.data ?? {}) as Record<string, unknown>;
+  node.data = {
+    ...data,
+    hProperties: { dataSoraneAlt: altText ?? "" },
+    soraneDiagram: { lang, altText, kind } satisfies SoraneDiagramMeta,
+  } as Code["data"];
+}
+
+/** remark プラグイン: mermaid / d2 フェンスに alt と kind メタデータを付与する。 */
+export function remarkDiagramFences(config: DiagramsConfig): Plugin<[], Root> {
+  return () => (tree: Root) => {
+    if (config.enabled === false) return;
+    visit(tree, "code", (node) => {
+      if (node.lang === "mermaid") {
+        if (config.mermaid?.mode === "off") return;
+        annotateDiagramCode(node, "mermaid");
+        return;
+      }
+      if (node.lang === "d2") {
+        if (config.d2?.enabled !== true) return;
+        annotateDiagramCode(node, "d2");
+        return;
+      }
+      if (isGraphvizLang(node.lang)) {
+        if (config.graphviz?.enabled !== true) return;
+        annotateDiagramCode(node, "graphviz");
+      }
+    });
+  };
+}

package/src/diagrams/rehype-diagram-pre.ts

@@ -0,0 +1,39 @@
+import type { Root as HastRoot, Element } from "hast";
+import { visit } from "unist-util-visit";
+
+function classNames(value: unknown): string[] {
+  if (typeof value === "string") return value.split(/\s+/).filter(Boolean);
+  if (Array.isArray(value)) {
+    return value.flatMap((v) => (typeof v === "string" ? v.split(/\s+/) : []));
+  }
+  return [];
+}
+
+function isDiagramCode(node: Element): boolean {
+  const cls = classNames(node.properties?.className);
+  return (
+    cls.includes("language-mermaid") ||
+    cls.includes("language-d2") ||
+    cls.includes("language-graphviz") ||
+    cls.includes("language-dot")
+  );
+}
+
+/** `pre > code.language-mermaid|d2` の alt を親 `pre` の data-sorane-alt へ移す。 */
+export function rehypeDiagramPre() {
+  return (tree: HastRoot) => {
+    visit(tree, "element", (node) => {
+      if (node.tagName !== "pre") return;
+      const code = node.children.find(
+        (c): c is Element => c.type === "element" && c.tagName === "code",
+      );
+      if (!code || !isDiagramCode(code)) return;
+      const alt = code.properties?.dataSoraneAlt;
+      if (typeof alt === "string" && alt.length > 0) {
+        node.properties ??= {};
+        node.properties.dataSoraneAlt = alt;
+        delete code.properties?.dataSoraneAlt;
+      }
+    });
+  };
+}

package/src/diagrams/remark-inject-built-figures.ts

@@ -0,0 +1,32 @@
+import type { Code, Root } from "mdast";
+import type { Plugin } from "unified";
+import { visit } from "unist-util-visit";
+import { escapeHtml } from "../render.ts";
+
+export type BuiltFigureVariant = "d2" | "mermaid" | "graphviz";
+
+export interface InjectedBuiltFigure {
+  readonly src: string;
+  readonly alt: string;
+  readonly variant: BuiltFigureVariant;
+}
+
+/** ビルド時コンパイル済みフェンスを raw HTML figure に差し替える。 */
+export function remarkInjectBuiltFigures(
+  figures: ReadonlyMap<Code, InjectedBuiltFigure>,
+): Plugin<[], Root> {
+  return () => (tree: Root) => {
+    visit(tree, "code", (node, index, parent) => {
+      if (parent === undefined || index === undefined) return;
+      const fig = figures.get(node);
+      if (!fig) return;
+      parent.children[index] = {
+        type: "html",
+        value:
+          `<figure class="diagram diagram--${fig.variant}" role="img" aria-label="${escapeHtml(fig.alt)}">` +
+          `<img src="${escapeHtml(fig.src)}" alt="${escapeHtml(fig.alt)}" loading="lazy" decoding="async" />` +
+          `</figure>`,
+      };
+    });
+  };
+}

package/src/diagrams/render-async.ts

@@ -0,0 +1,241 @@
+import type { Code, Root } from "mdast";
+import type { DiagramsConfig } from "../config.ts";
+import { DEFAULT_DIAGRAMS_CONFIG } from "../config.ts";
+import {
+  countDiagramsForConfig,
+  type DiagramRenderMeta,
+} from "./diagram-meta.ts";
+import {
+  compileD2ToSvg,
+  isD2CompileEnabled,
+  resolveD2Binary,
+} from "./compile-d2.ts";
+import {
+  compileGraphvizToSvg,
+  isGraphvizCompileEnabled,
+  isGraphvizLang,
+  resolveGraphvizBinary,
+} from "./compile-graphviz.ts";
+import {
+  compileMermaidToSvg,
+  isMermaidBuildEnabled,
+  resolveMmdcBinary,
+} from "./compile-mermaid.ts";
+import { extractAltText } from "./parse-diagram-fence.ts";
+import {
+  remarkInjectBuiltFigures,
+  type InjectedBuiltFigure,
+} from "./remark-inject-built-figures.ts";
+import { remarkDiagramFences } from "./parse-diagram-fence.ts";
+import { rehypeDiagramPre } from "./rehype-diagram-pre.ts";
+import type {
+  RenderOptions,
+  RenderedMarkdown,
+  TocEntry,
+} from "../render.ts";
+import { rewriteLinks, sanitizeSchema } from "../render.ts";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeRaw from "rehype-raw";
+import rehypeSanitize from "rehype-sanitize";
+import rehypeStringify from "rehype-stringify";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import { SlugLedger } from "@sorane/search";
+import type { Root as HastRoot } from "hast";
+import { visit } from "unist-util-visit";
+
+function hastToPlainText(node: {
+  type?: string;
+  value?: string;
+  children?: unknown[];
+}): string {
+  if (node.type === "text" && typeof node.value === "string") return node.value;
+  if (!node.children) return "";
+  return node.children
+    .map((child) =>
+      hastToPlainText(child as { type?: string; value?: string; children?: unknown[] }),
+    )
+    .join("");
+}
+
+function rehypeHeadingIds() {
+  const ledger = new SlugLedger();
+  return (tree: HastRoot) => {
+    visit(tree, "element", (node) => {
+      const m = /^h([1-6])$/.exec(node.tagName);
+      if (!m) return;
+      const text = hastToPlainText(node).trim();
+      if (!text) return;
+      node.properties ??= {};
+      node.properties.id = ledger.next(text);
+    });
+  };
+}
+
+function rehypeCollectOutline(outline: TocEntry[]) {
+  return () => (tree: HastRoot) => {
+    visit(tree, "element", (node) => {
+      const m = /^h([2-4])$/.exec(node.tagName);
+      if (!m) return;
+      const id = node.properties?.id;
+      if (typeof id !== "string" || id.length === 0) return;
+      const text = hastToPlainText(node)
+        .replace(/\s*#\s*$/, "")
+        .trim();
+      if (!text) return;
+      outline.push({ depth: Number(m[1]), id, text });
+    });
+  };
+}
+
+export interface AsyncRenderOptions extends RenderOptions {
+  readonly rootPrefix?: string;
+  readonly d2OutDir?: string;
+  readonly mermaidOutDir?: string;
+  readonly graphvizOutDir?: string;
+  readonly onDiagramWarning?: (message: string) => void;
+}
+
+async function compileBuiltFigures(
+  tree: Root,
+  diagramConfig: DiagramsConfig,
+  opts: AsyncRenderOptions,
+): Promise<ReadonlyMap<Code, InjectedBuiltFigure>> {
+  const figures = new Map<Code, InjectedBuiltFigure>();
+  const rootPrefix = opts.rootPrefix ?? "./";
+  const warn = opts.onDiagramWarning;
+
+  if (isD2CompileEnabled(diagramConfig) && opts.d2OutDir) {
+    const binary = resolveD2Binary(diagramConfig);
+    const d2Nodes: Code[] = [];
+    visit(tree, "code", (node) => {
+      if (node.lang === "d2") d2Nodes.push(node);
+    });
+    for (const node of d2Nodes) {
+      const alt = extractAltText(node.meta, node.value) ?? "Diagram";
+      const result = await compileD2ToSvg({
+        source: node.value,
+        binary,
+        outDir: opts.d2OutDir,
+      });
+      if (!result.ok) {
+        warn?.(
+          `diagrams: d2 compile failed (${result.hash.slice(0, 8)}…): ${result.warning ?? "unknown error"}`,
+        );
+        continue;
+      }
+      figures.set(node, {
+        src: `${rootPrefix}assets/diagrams/d2/${result.svgFileName}`,
+        alt,
+        variant: "d2",
+      });
+    }
+  }
+
+  if (isMermaidBuildEnabled(diagramConfig) && opts.mermaidOutDir) {
+    const binary = resolveMmdcBinary(diagramConfig);
+    const mermaidNodes: Code[] = [];
+    visit(tree, "code", (node) => {
+      if (node.lang === "mermaid") mermaidNodes.push(node);
+    });
+    for (const node of mermaidNodes) {
+      const alt = extractAltText(node.meta, node.value) ?? "Diagram";
+      const result = await compileMermaidToSvg({
+        source: node.value,
+        binary,
+        outDir: opts.mermaidOutDir,
+      });
+      if (!result.ok) {
+        warn?.(
+          `diagrams: mermaid build failed (${result.hash.slice(0, 8)}…): ${result.warning ?? "unknown error"}`,
+        );
+        continue;
+      }
+      figures.set(node, {
+        src: `${rootPrefix}assets/diagrams/mermaid/${result.svgFileName}`,
+        alt,
+        variant: "mermaid",
+      });
+    }
+  }
+
+  if (isGraphvizCompileEnabled(diagramConfig) && opts.graphvizOutDir) {
+    const binary = resolveGraphvizBinary(diagramConfig);
+    const gvNodes: Code[] = [];
+    visit(tree, "code", (node) => {
+      if (isGraphvizLang(node.lang)) gvNodes.push(node);
+    });
+    for (const node of gvNodes) {
+      const alt = extractAltText(node.meta, node.value) ?? "Diagram";
+      const result = await compileGraphvizToSvg({
+        source: node.value,
+        binary,
+        outDir: opts.graphvizOutDir,
+      });
+      if (!result.ok) {
+        warn?.(
+          `diagrams: graphviz compile failed (${result.hash.slice(0, 8)}…): ${result.warning ?? "unknown error"}`,
+        );
+        continue;
+      }
+      figures.set(node, {
+        src: `${rootPrefix}assets/diagrams/graphviz/${result.svgFileName}`,
+        alt,
+        variant: "graphviz",
+      });
+    }
+  }
+
+  return figures;
+}
+
+/** Markdown 本文を非同期で変換する（ビルド時コンパイルバックエンド用）。 */
+export async function renderMarkdownDocumentAsync(
+  markdown: string,
+  opts?: AsyncRenderOptions,
+): Promise<RenderedMarkdown> {
+  const diagramConfig = opts?.diagrams ?? DEFAULT_DIAGRAMS_CONFIG;
+  const outline: TocEntry[] = [];
+  const diagrams: DiagramRenderMeta = { mermaid: 0, d2: 0, graphviz: 0 };
+
+  const tree = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkDiagramFences(diagramConfig))
+    .parse(rewriteLinks(markdown)) as Root;
+
+  Object.assign(diagrams, countDiagramsForConfig(tree, diagramConfig));
+  const builtFigures = await compileBuiltFigures(tree, diagramConfig, opts ?? {});
+
+  const processor = unified()
+    .use(remarkInjectBuiltFigures(builtFigures))
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeRaw)
+    .use(rehypeDiagramPre)
+    .use(rehypeHeadingIds)
+    .use(rehypeAutolinkHeadings, {
+      behavior: "append",
+      properties: {
+        className: ["heading-anchor"],
+        ariaHidden: "true",
+        tabIndex: -1,
+      },
+      content: { type: "text", value: "#" },
+    })
+    .use(rehypeCollectOutline(outline))
+    .use(rehypeSanitize, sanitizeSchema)
+    .use(rehypeStringify);
+
+  const html = processor
+    .stringify(processor.runSync(tree))
+    .replace(/\r\n?/g, "\n")
+    .trimEnd();
+
+  return {
+    html: html.length > 0 ? `${html}\n` : "",
+    outline,
+    diagrams,
+  };
+}