radiant-docs 0.1.6 → 0.1.8

package/template/src/lib/code/code-block.ts

@@ -0,0 +1,546 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  bundledLanguagesInfo,
+  bundledLanguages,
+  getSingletonHighlighter,
+  type ThemedToken,
+} from "shiki";
+import { DEFAULT_FILE, getIconForFile } from "vscode-icons-js";
+
+export const DEFAULT_CODE_BLOCK_LANGUAGE = "plaintext";
+
+const SHIKI_LANGUAGE_ALIAS_TO_VALUE: Record<string, string> = (() => {
+  const aliasToValueMap: Record<string, string> = Object.create(null);
+
+  for (const languageInfo of bundledLanguagesInfo) {
+    const id = languageInfo.id.toLowerCase();
+    aliasToValueMap[id] = id;
+
+    for (const alias of languageInfo.aliases ?? []) {
+      const normalizedAlias = alias.toLowerCase();
+      aliasToValueMap[normalizedAlias] = id;
+    }
+  }
+
+  return aliasToValueMap;
+})();
+
+const LANGUAGE_ALIAS_COMPAT_TO_VALUE: Record<string, string> = {
+  text: "plaintext",
+  plain: "plaintext",
+  txt: "plaintext",
+  node: "javascript",
+  graphqls: "graphql",
+  htm: "html",
+};
+
+const FILE_EXTENSION_BY_LANGUAGE: Record<string, string> = {
+  bash: "sh",
+  shell: "sh",
+  shellscript: "sh",
+  c: "c",
+  cpp: "cpp",
+  csharp: "cs",
+  css: "css",
+  diff: "diff",
+  go: "go",
+  graphql: "graphql",
+  html: "html",
+  java: "java",
+  javascript: "js",
+  jsx: "jsx",
+  json: "json",
+  kotlin: "kt",
+  markdown: "md",
+  mdx: "mdx",
+  php: "php",
+  plaintext: "txt",
+  python: "py",
+  ruby: "rb",
+  rust: "rs",
+  sql: "sql",
+  swift: "swift",
+  toml: "toml",
+  typescript: "ts",
+  tsx: "tsx",
+  xml: "xml",
+  yaml: "yml",
+};
+
+const CODE_BLOCK_LANGUAGE_BY_FILE_EXTENSION: Record<string, string> = {
+  sh: "shellscript",
+  c: "c",
+  cpp: "cpp",
+  cc: "cpp",
+  cxx: "cpp",
+  cs: "csharp",
+  css: "css",
+  diff: "diff",
+  go: "go",
+  graphql: "graphql",
+  gql: "graphql",
+  htm: "html",
+  html: "html",
+  java: "java",
+  js: "javascript",
+  jsx: "jsx",
+  json: "json",
+  kt: "kotlin",
+  md: "markdown",
+  mdx: "mdx",
+  markdown: "markdown",
+  php: "php",
+  py: "python",
+  rb: "ruby",
+  rs: "rust",
+  sql: "sql",
+  swift: "swift",
+  toml: "toml",
+  ts: "typescript",
+  tsx: "tsx",
+  xml: "xml",
+  yaml: "yaml",
+  yml: "yaml",
+};
+
+const CODE_BLOCK_LANGUAGE_ICON_FILE_BY_VALUE: Record<string, string> = {
+  bash: "file_type_shell.svg",
+  shell: "file_type_shell.svg",
+  shellscript: "file_type_shell.svg",
+  c: "file_type_c.svg",
+  cpp: "file_type_cpp.svg",
+  csharp: "file_type_csharp.svg",
+  css: "file_type_css.svg",
+  diff: "file_type_diff.svg",
+  go: "file_type_go.svg",
+  graphql: "file_type_graphql.svg",
+  html: "file_type_html.svg",
+  java: "file_type_java.svg",
+  javascript: "file_type_js_official.svg",
+  jsx: "file_type_reactjs.svg",
+  json: "file_type_json_official.svg",
+  kotlin: "file_type_kotlin.svg",
+  markdown: "file_type_markdown.svg",
+  mdx: "file_type_markdown.svg",
+  php: "file_type_php.svg",
+  plaintext: "default_file.svg",
+  python: "file_type_python.svg",
+  ruby: "file_type_ruby.svg",
+  rust: "file_type_rust.svg",
+  sql: "file_type_sql.svg",
+  swift: "file_type_swift.svg",
+  toml: "file_type_toml.svg",
+  typescript: "file_type_typescript_official.svg",
+  tsx: "file_type_reactts.svg",
+  xml: "file_type_xml.svg",
+  yaml: "file_type_yaml_official.svg",
+};
+
+const SHIKI_THEME = "github-light";
+const BUNDLED_LANGUAGE_SET = new Set(Object.keys(bundledLanguages));
+const LANGUAGE_RUNTIME_DEPENDENCIES: Record<string, string[]> = {
+  // MDX tokenization relies on TSX grammar injections for JSX-style tags.
+  // Without TSX loaded first, Shiki can return mostly plain tokens.
+  mdx: ["tsx"],
+};
+
+const ICON_DIRECTORY = path.resolve(
+  process.cwd(),
+  "node_modules/@xt0rted/expressive-code-file-icons/dist/icons",
+);
+
+const iconSvgCache = new Map<string, string>();
+let iconSvgInstanceCounter = 0;
+let iconFileNameSetPromise: Promise<Set<string>> | null = null;
+
+let highlighterPromise:
+  | Promise<Awaited<ReturnType<typeof getSingletonHighlighter>>>
+  | null = null;
+const loadedLanguageSet = new Set<string>([DEFAULT_CODE_BLOCK_LANGUAGE]);
+const languageLoadPromiseByName = new Map<string, Promise<void>>();
+
+function resolveAliasLanguage(rawValue: string): string {
+  const normalized = rawValue.trim().toLowerCase();
+  if (!normalized) return "";
+
+  const firstToken = normalized.split(/\s+/)[0] ?? "";
+  if (!firstToken) return "";
+
+  const tokenMatch = firstToken.match(/[a-z0-9+#-]+/i);
+  const token = (tokenMatch?.[0] ?? firstToken).toLowerCase();
+  return (
+    SHIKI_LANGUAGE_ALIAS_TO_VALUE[token] ??
+    LANGUAGE_ALIAS_COMPAT_TO_VALUE[token] ??
+    token
+  );
+}
+
+function resolveLanguageFromFileName(fileName: string): string {
+  const extensionIndex = fileName.lastIndexOf(".");
+  if (extensionIndex < 0 || extensionIndex >= fileName.length - 1) return "";
+  const extension = fileName.slice(extensionIndex + 1).toLowerCase();
+  return CODE_BLOCK_LANGUAGE_BY_FILE_EXTENSION[extension] ?? "";
+}
+
+async function getIconFileNameSet(): Promise<Set<string>> {
+  if (!iconFileNameSetPromise) {
+    iconFileNameSetPromise = fs
+      .readdir(ICON_DIRECTORY)
+      .then((entries) => new Set(entries))
+      .catch(() => new Set<string>(["default_file.svg"]));
+  }
+
+  return iconFileNameSetPromise;
+}
+
+async function hasIconFileName(iconFileName: string): Promise<boolean> {
+  const iconFileNameSet = await getIconFileNameSet();
+  return iconFileNameSet.has(iconFileName);
+}
+
+function uniqueValues(values: string[]): string[] {
+  return Array.from(new Set(values.filter((value) => value.length > 0)));
+}
+
+function sanitizeIconLookupToken(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "");
+}
+
+function buildIconLookupTokens(language: string): string[] {
+  const baseToken = sanitizeIconLookupToken(language);
+  if (!baseToken) return [];
+
+  const kebabToken = baseToken
+    .replace(/_/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  const snakeToken = kebabToken.replace(/-/g, "_");
+  const compactToken = snakeToken.replace(/_/g, "");
+
+  return uniqueValues([baseToken, kebabToken, snakeToken, compactToken]);
+}
+
+function pickIconFromFileName(fileName: string): string | null {
+  const trimmedFileName = fileName.trim();
+  if (!trimmedFileName) return null;
+
+  const candidates = uniqueValues([trimmedFileName, trimmedFileName.toLowerCase()]);
+  for (const candidate of candidates) {
+    const iconFileName = getIconForFile(candidate);
+    if (iconFileName !== DEFAULT_FILE) return iconFileName;
+  }
+
+  return null;
+}
+
+async function resolveIconFileName(
+  language: string,
+  fileName: string,
+): Promise<string> {
+  const resolvedLanguage = resolveAliasLanguage(language);
+  const languageFromFileName = fileName
+    ? resolveAliasLanguage(resolveLanguageFromFileName(fileName))
+    : "";
+
+  // Preserve explicit icon choices for core languages.
+  const explicitIconLanguageCandidates = uniqueValues([
+    resolvedLanguage,
+    languageFromFileName,
+  ]);
+  for (const candidate of explicitIconLanguageCandidates) {
+    const mappedIconFileName = CODE_BLOCK_LANGUAGE_ICON_FILE_BY_VALUE[candidate];
+    if (mappedIconFileName && (await hasIconFileName(mappedIconFileName))) {
+      return mappedIconFileName;
+    }
+  }
+
+  // Use vscode-icons-js matching first for best coverage.
+  const hasMappedDefaultExtension =
+    !!resolvedLanguage && FILE_EXTENSION_BY_LANGUAGE[resolvedLanguage] !== undefined;
+  const mappedDefaultFileName = hasMappedDefaultExtension
+    ? buildDefaultCodeFileName(resolvedLanguage)
+    : "";
+  const fileNameCandidates = uniqueValues([
+    fileName.trim(),
+    resolvedLanguage ? `file.${resolvedLanguage}` : "",
+    languageFromFileName ? `file.${languageFromFileName}` : "",
+    language ? `file.${language.trim().toLowerCase()}` : "",
+    mappedDefaultFileName,
+  ]);
+  for (const candidate of fileNameCandidates) {
+    const matchedIconFileName = pickIconFromFileName(candidate);
+    if (matchedIconFileName && (await hasIconFileName(matchedIconFileName))) {
+      return matchedIconFileName;
+    }
+  }
+
+  // Last attempt: direct language icon file lookup.
+  const iconTokenCandidates = uniqueValues([
+    ...buildIconLookupTokens(resolvedLanguage),
+    ...buildIconLookupTokens(languageFromFileName),
+    ...buildIconLookupTokens(language),
+  ]);
+  for (const token of iconTokenCandidates) {
+    const directIconFileNames = [
+      `file_type_${token}.svg`,
+      `file_type_light_${token}.svg`,
+    ];
+    for (const iconFileName of directIconFileNames) {
+      if (await hasIconFileName(iconFileName)) return iconFileName;
+    }
+  }
+
+  return "default_file.svg";
+}
+
+async function readIconSvg(iconFileName: string): Promise<string> {
+  const cached = iconSvgCache.get(iconFileName);
+  if (cached) return cached;
+
+  const filePath = path.join(ICON_DIRECTORY, iconFileName);
+  const svg = await fs.readFile(filePath, "utf8");
+  iconSvgCache.set(iconFileName, svg);
+  return svg;
+}
+
+function addClassToSvgRoot(svg: string, className: string): string {
+  const openTagStart = svg.indexOf("<svg");
+  if (openTagStart === -1) return svg;
+
+  const openTagEnd = svg.indexOf(">", openTagStart);
+  if (openTagEnd === -1) return svg;
+
+  const openTag = svg.slice(openTagStart, openTagEnd);
+  const classMatch = openTag.match(/\sclass=(["'])(.*?)\1/);
+
+  if (classMatch) {
+    const existingClass = classMatch[2].trim();
+    const nextClass = existingClass.length
+      ? `${existingClass} ${className}`
+      : className;
+    const nextTag = openTag.replace(
+      /\sclass=(["'])(.*?)\1/,
+      ` class="${nextClass}"`,
+    );
+    return `${svg.slice(0, openTagStart)}${nextTag}${svg.slice(openTagEnd)}`;
+  }
+
+  const withClass = `${openTag} class="${className}"`;
+  return `${svg.slice(0, openTagStart)}${withClass}${svg.slice(openTagEnd)}`;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function namespaceSvgIds(svg: string, namespace: string): string {
+  const idMatches = [...svg.matchAll(/\bid=(["'])([^"']+)\1/g)];
+  if (idMatches.length === 0) return svg;
+
+  const idMap = new Map<string, string>();
+  for (const match of idMatches) {
+    const idValue = match[2];
+    if (!idMap.has(idValue)) {
+      idMap.set(idValue, `${idValue}-${namespace}`);
+    }
+  }
+
+  let namespacedSvg = svg;
+  for (const [originalId, namespacedId] of idMap) {
+    const escapedId = escapeRegExp(originalId);
+
+    namespacedSvg = namespacedSvg.replace(
+      new RegExp(`\\bid=(["'])${escapedId}\\1`, "g"),
+      `id="${namespacedId}"`,
+    );
+
+    namespacedSvg = namespacedSvg.replace(
+      new RegExp(`url\\(#${escapedId}\\)`, "g"),
+      `url(#${namespacedId})`,
+    );
+
+    namespacedSvg = namespacedSvg.replace(
+      new RegExp(`\\b(href|xlink:href)=(["'])#${escapedId}\\2`, "g"),
+      `$1="#${namespacedId}"`,
+    );
+  }
+
+  return namespacedSvg;
+}
+
+async function getHighlighter() {
+  if (!highlighterPromise) {
+    highlighterPromise = getSingletonHighlighter({
+      themes: [SHIKI_THEME],
+      langs: [DEFAULT_CODE_BLOCK_LANGUAGE],
+    });
+  }
+
+  return highlighterPromise;
+}
+
+function resolveLoadableLanguage(
+  highlighter: Awaited<ReturnType<typeof getSingletonHighlighter>>,
+  normalizedLanguage: string,
+): string | null {
+  const aliasResolvedLanguage = highlighter.resolveLangAlias(normalizedLanguage);
+
+  if (
+    typeof aliasResolvedLanguage === "string" &&
+    aliasResolvedLanguage.length > 0 &&
+    BUNDLED_LANGUAGE_SET.has(aliasResolvedLanguage)
+  ) {
+    return aliasResolvedLanguage;
+  }
+
+  if (BUNDLED_LANGUAGE_SET.has(normalizedLanguage)) {
+    return normalizedLanguage;
+  }
+
+  return null;
+}
+
+async function ensureLanguageLoaded(
+  highlighter: Awaited<ReturnType<typeof getSingletonHighlighter>>,
+  language: string,
+): Promise<void> {
+  if (!language || loadedLanguageSet.has(language)) return;
+
+  const existingLoadPromise = languageLoadPromiseByName.get(language);
+  if (existingLoadPromise) {
+    await existingLoadPromise;
+    return;
+  }
+
+  const loadPromise = highlighter
+    .loadLanguage(language)
+    .then(() => {
+      loadedLanguageSet.add(language);
+    })
+    .finally(() => {
+      languageLoadPromiseByName.delete(language);
+    });
+
+  languageLoadPromiseByName.set(language, loadPromise);
+  await loadPromise;
+}
+
+function buildLanguageLoadOrder(language: string): string[] {
+  const orderedLanguages: string[] = [];
+  const visitedLanguageSet = new Set<string>();
+
+  const visitLanguage = (languageValue: string) => {
+    if (!languageValue || visitedLanguageSet.has(languageValue)) return;
+    visitedLanguageSet.add(languageValue);
+
+    const dependencyLanguages =
+      LANGUAGE_RUNTIME_DEPENDENCIES[languageValue] ?? [];
+    for (const dependencyLanguage of dependencyLanguages) {
+      visitLanguage(dependencyLanguage);
+    }
+
+    orderedLanguages.push(languageValue);
+  };
+
+  visitLanguage(language);
+  return orderedLanguages;
+}
+
+export function normalizeCodeLanguageValue(rawLanguage: string): string {
+  const normalizedLanguage = resolveAliasLanguage(rawLanguage);
+  return normalizedLanguage || DEFAULT_CODE_BLOCK_LANGUAGE;
+}
+
+export function buildDefaultCodeFileName(language: string): string {
+  const normalizedLanguage = normalizeCodeLanguageValue(language);
+  const extension = FILE_EXTENSION_BY_LANGUAGE[normalizedLanguage] ?? "txt";
+  return `file-name.${extension}`;
+}
+
+export async function getLanguageIconSvg({
+  language,
+  fileName,
+  className,
+}: {
+  language: string;
+  fileName: string;
+  className: string;
+}): Promise<string> {
+  const iconFileName = await resolveIconFileName(language, fileName);
+
+  let iconSvg = "";
+  try {
+    iconSvg = await readIconSvg(iconFileName);
+  } catch {
+    iconSvg = await readIconSvg("default_file.svg");
+  }
+
+  iconSvgInstanceCounter += 1;
+  const namespacedSvg = namespaceSvgIds(
+    iconSvg,
+    `rd-icon-${iconSvgInstanceCounter.toString(36)}`,
+  );
+
+  return addClassToSvgRoot(namespacedSvg, className);
+}
+
+export async function getCodeLineTokens({
+  code,
+  language,
+}: {
+  code: string;
+  language: string;
+}): Promise<{
+  normalizedLanguage: string;
+  lines: ThemedToken[][];
+}> {
+  const highlighter = await getHighlighter();
+  const normalizedLanguage = normalizeCodeLanguageValue(language);
+  const loadableLanguage = resolveLoadableLanguage(
+    highlighter,
+    normalizedLanguage,
+  );
+  const targetLanguage = loadableLanguage ?? DEFAULT_CODE_BLOCK_LANGUAGE;
+
+  if (targetLanguage !== DEFAULT_CODE_BLOCK_LANGUAGE) {
+    const languageLoadOrder = buildLanguageLoadOrder(targetLanguage);
+    try {
+      for (const languageToLoad of languageLoadOrder) {
+        if (languageToLoad === DEFAULT_CODE_BLOCK_LANGUAGE) continue;
+
+        const loadableDependencyLanguage = resolveLoadableLanguage(
+          highlighter,
+          languageToLoad,
+        );
+        if (!loadableDependencyLanguage) continue;
+
+        await ensureLanguageLoaded(highlighter, loadableDependencyLanguage);
+      }
+    } catch {
+      // Fall through to plaintext rendering below.
+    }
+  }
+
+  try {
+    const tokenResult = highlighter.codeToTokens(code, {
+      lang: targetLanguage,
+      theme: SHIKI_THEME,
+    });
+
+    return {
+      normalizedLanguage: targetLanguage,
+      lines: tokenResult.tokens,
+    };
+  } catch {
+    const tokenResult = highlighter.codeToTokens(code, {
+      lang: DEFAULT_CODE_BLOCK_LANGUAGE,
+      theme: SHIKI_THEME,
+    });
+
+    return {
+      normalizedLanguage: DEFAULT_CODE_BLOCK_LANGUAGE,
+      lines: tokenResult.tokens,
+    };
+  }
+}

package/template/src/lib/frontmatter-schema.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
 
-export const docsSchema = z.object({
-  title: z
-    .string({
-      invalid_type_error: "'title' must be a text string.",
-    })
-    .optional(),
-});
+// Frontmatter schema for MDX files.
+// `title` controls the rendered page title (not navigation labels).
+export const docsSchema = z
+  .object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough();