boltdocs 1.0.4 → 1.3.1

package/src/node/routes/cache.ts

@@ -1,24 +1,28 @@
-import { FileCache } from "../cache";
-import { ParsedDocFile } from "./types";
-
-const docCache = new FileCache<ParsedDocFile>();
-
-/**
- * Invalidate all cached routes.
- * Typically called when a file is added or deleted, requiring a complete route rebuild.
- */
-export function invalidateRouteCache(): void {
-  docCache.invalidateAll();
-}
-
-/**
- * Invalidate a specific file from cache.
- * Called when a specific file is modified (changed).
- *
- * @param filePath - The absolute path of the file to invalidate
- */
-export function invalidateFile(filePath: string): void {
-  docCache.invalidate(filePath);
-}
-
-export { docCache };
+import { FileCache } from "../cache";
+import { ParsedDocFile } from "./types";
+
+/**
+ * Persistent cache for parsed documentation files.
+ * Saves data to `.boltdocs/routes.json`.
+ */
+const docCache = new FileCache<ParsedDocFile>({ name: "routes" });
+
+/**
+ * Invalidate all cached routes.
+ * Typically called when a file is added or deleted, requiring a complete route rebuild.
+ */
+export function invalidateRouteCache(): void {
+  docCache.invalidateAll();
+}
+
+/**
+ * Invalidate a specific file from cache.
+ * Called when a specific file is modified (changed).
+ *
+ * @param filePath - The absolute path of the file to invalidate
+ */
+export function invalidateFile(filePath: string): void {
+  docCache.invalidate(filePath);
+}
+
+export { docCache };

package/src/node/routes/index.ts

@@ -1,152 +1,167 @@
-import fastGlob from "fast-glob";
-import { BoltdocsConfig } from "../config";
-import { capitalize } from "../utils";
-
-import { RouteMeta, ParsedDocFile } from "./types";
-import { docCache, invalidateRouteCache, invalidateFile } from "./cache";
-import { parseDocFile } from "./parser";
-import { sortRoutes } from "./sorter";
-
-// Re-export public API
-export type { RouteMeta };
-export { invalidateRouteCache, invalidateFile };
-
-/**
- * Generates the entire route map for the documentation site.
- * This reads all `.md` and `.mdx` files in the `docsDir`, parses them (using cache),
- * infers group hierarchies based on directory structure and `index.md` files,
- * and returns a sorted array of RouteMeta objects intended for the client.
- *
- * @param docsDir - The root directory containing markdown files
- * @param config - Optional configuration for i18n and versioning
- * @param basePath - The base URL path to prefix to generated routes (e.g., '/docs')
- * @returns A promise that resolves to the final list of RouteMeta objects
- */
-export async function generateRoutes(
-  docsDir: string,
-  config?: BoltdocsConfig,
-  basePath: string = "/docs",
-): Promise<RouteMeta[]> {
-  const files = await fastGlob(["**/*.md", "**/*.mdx"], {
-    cwd: docsDir,
-    absolute: true,
-  });
-
-  // Prune cache entries for deleted files
-  docCache.pruneStale(new Set(files));
-
-  // Invalidate all caches if config changes drastically (e.g. i18n enabled)
-  if (config?.i18n) {
-    docCache.invalidateAll();
-  }
-
-  // Parse files in parallel using Promise.all for increased efficiency
-  const parsed: ParsedDocFile[] = await Promise.all(
-    files.map(async (file) => {
-      const cached = docCache.get(file);
-      if (cached) return cached;
-
-      const result = parseDocFile(file, docsDir, basePath, config);
-      docCache.set(file, result);
-      return result;
-    }),
-  );
-
-  // Collect group metadata from directory names and index files
-  const groupMeta = new Map<string, { title: string; position?: number }>();
-  for (const p of parsed) {
-    if (p.relativeDir) {
-      if (!groupMeta.has(p.relativeDir)) {
-        groupMeta.set(p.relativeDir, {
-          title: capitalize(p.relativeDir),
-          position: p.inferredGroupPosition,
-        });
-      } else {
-        const entry = groupMeta.get(p.relativeDir)!;
-        if (
-          entry.position === undefined &&
-          p.inferredGroupPosition !== undefined
-        ) {
-          entry.position = p.inferredGroupPosition;
-        }
-      }
-    }
-
-    if (p.isGroupIndex && p.relativeDir && p.groupMeta) {
-      const entry = groupMeta.get(p.relativeDir)!;
-      entry.title = p.groupMeta.title;
-      if (p.groupMeta.position !== undefined) {
-        entry.position = p.groupMeta.position;
-      }
-    }
-  }
-
-  // Build final routes with group info
-  const routes: RouteMeta[] = parsed.map((p) => {
-    const dir = p.relativeDir;
-    const meta = dir ? groupMeta.get(dir) : undefined;
-
-    return {
-      ...p.route,
-      group: dir,
-      groupTitle: meta?.title || (dir ? capitalize(dir) : undefined),
-      groupPosition: meta?.position,
-    };
-  });
-
-  // Add fallbacks if i18n is enabled
-  if (config?.i18n) {
-    const defaultLocale = config.i18n.defaultLocale;
-    const allLocales = Object.keys(config.i18n.locales);
-
-    const fallbackRoutes: RouteMeta[] = [];
-    const defaultRoutes = routes.filter(
-      (r) => (r.locale || defaultLocale) === defaultLocale,
-    );
-
-    for (const locale of allLocales) {
-      if (locale === defaultLocale) continue;
-
-      const localeRoutePaths = new Set(
-        routes.filter((r) => r.locale === locale).map((r) => r.path),
-      );
-
-      for (const defRoute of defaultRoutes) {
-        let prefix = basePath;
-        if (defRoute.version) {
-          prefix += "/" + defRoute.version;
-        }
-
-        let pathAfterVersion = defRoute.path.substring(prefix.length);
-
-        if (pathAfterVersion.startsWith("/" + defaultLocale + "/")) {
-          pathAfterVersion = pathAfterVersion.substring(
-            defaultLocale.length + 1,
-          );
-        } else if (pathAfterVersion === "/" + defaultLocale) {
-          pathAfterVersion = "/";
-        }
-
-        const targetPath =
-          prefix +
-          "/" +
-          locale +
-          (pathAfterVersion === "/" || pathAfterVersion === ""
-            ? ""
-            : pathAfterVersion);
-
-        if (!localeRoutePaths.has(targetPath)) {
-          fallbackRoutes.push({
-            ...defRoute,
-            path: targetPath,
-            locale: locale,
-          });
-        }
-      }
-    }
-
-    return sortRoutes([...routes, ...fallbackRoutes]);
-  }
-
-  return sortRoutes(routes);
-}
+import fastGlob from "fast-glob";
+import { BoltdocsConfig } from "../config";
+import { capitalize } from "../utils";
+
+import { RouteMeta, ParsedDocFile } from "./types";
+import { docCache, invalidateRouteCache, invalidateFile } from "./cache";
+import { parseDocFile } from "./parser";
+import { sortRoutes } from "./sorter";
+
+// Re-export public API
+export type { RouteMeta };
+export { invalidateRouteCache, invalidateFile };
+
+/**
+ * Generates the entire route map for the documentation site.
+ * This reads all `.md` and `.mdx` files in the `docsDir`, parses them (using cache),
+ * infers group hierarchies based on directory structure and `index.md` files,
+ * and returns a sorted array of RouteMeta objects intended for the client.
+ *
+ * @param docsDir - The root directory containing markdown files
+ * @param config - Optional configuration for i18n and versioning
+ * @param basePath - The base URL path to prefix to generated routes (e.g., '/docs')
+ * @returns A promise that resolves to the final list of RouteMeta objects
+ */
+export async function generateRoutes(
+  docsDir: string,
+  config?: BoltdocsConfig,
+  basePath: string = "/docs",
+): Promise<RouteMeta[]> {
+  // Load persistent cache on first call
+  docCache.load();
+
+  const files = await fastGlob(["**/*.md", "**/*.mdx"], {
+    cwd: docsDir,
+    absolute: true,
+  });
+
+  // Prune cache entries for deleted files
+  docCache.pruneStale(new Set(files));
+
+  // Invalidate all caches if config changes drastically (e.g. i18n enabled)
+  if (config?.i18n) {
+    docCache.invalidateAll();
+  }
+
+  // Parse files in parallel using Promise.all for increased efficiency
+  let cacheHits = 0;
+  const parsed: ParsedDocFile[] = await Promise.all(
+    files.map(async (file) => {
+      const cached = docCache.get(file);
+      if (cached) {
+        cacheHits++;
+        return cached;
+      }
+
+      const result = parseDocFile(file, docsDir, basePath, config);
+      docCache.set(file, result);
+      return result;
+    }),
+  );
+
+  if (files.length > 0) {
+    console.log(
+      `[boltdocs] Routes generated: ${files.length} files (${cacheHits} from cache, ${files.length - cacheHits} parsed)`,
+    );
+  }
+
+  // Save cache after batch processing
+  docCache.save();
+
+  // Collect group metadata from directory names and index files
+  const groupMeta = new Map<string, { title: string; position?: number }>();
+  for (const p of parsed) {
+    if (p.relativeDir) {
+      if (!groupMeta.has(p.relativeDir)) {
+        groupMeta.set(p.relativeDir, {
+          title: capitalize(p.relativeDir),
+          position: p.inferredGroupPosition,
+        });
+      } else {
+        const entry = groupMeta.get(p.relativeDir)!;
+        if (
+          entry.position === undefined &&
+          p.inferredGroupPosition !== undefined
+        ) {
+          entry.position = p.inferredGroupPosition;
+        }
+      }
+    }
+
+    if (p.isGroupIndex && p.relativeDir && p.groupMeta) {
+      const entry = groupMeta.get(p.relativeDir)!;
+      entry.title = p.groupMeta.title;
+      if (p.groupMeta.position !== undefined) {
+        entry.position = p.groupMeta.position;
+      }
+    }
+  }
+
+  // Build final routes with group info
+  const routes: RouteMeta[] = parsed.map((p) => {
+    const dir = p.relativeDir;
+    const meta = dir ? groupMeta.get(dir) : undefined;
+
+    return {
+      ...p.route,
+      group: dir,
+      groupTitle: meta?.title || (dir ? capitalize(dir) : undefined),
+      groupPosition: meta?.position,
+    };
+  });
+
+  // Add fallbacks if i18n is enabled
+  if (config?.i18n) {
+    const defaultLocale = config.i18n.defaultLocale;
+    const allLocales = Object.keys(config.i18n.locales);
+
+    const fallbackRoutes: RouteMeta[] = [];
+    const defaultRoutes = routes.filter(
+      (r) => (r.locale || defaultLocale) === defaultLocale,
+    );
+
+    for (const locale of allLocales) {
+      if (locale === defaultLocale) continue;
+
+      const localeRoutePaths = new Set(
+        routes.filter((r) => r.locale === locale).map((r) => r.path),
+      );
+
+      for (const defRoute of defaultRoutes) {
+        let prefix = basePath;
+        if (defRoute.version) {
+          prefix += "/" + defRoute.version;
+        }
+
+        let pathAfterVersion = defRoute.path.substring(prefix.length);
+
+        if (pathAfterVersion.startsWith("/" + defaultLocale + "/")) {
+          pathAfterVersion = pathAfterVersion.substring(
+            defaultLocale.length + 1,
+          );
+        } else if (pathAfterVersion === "/" + defaultLocale) {
+          pathAfterVersion = "/";
+        }
+        const targetPath =
+          prefix +
+          "/" +
+          locale +
+          (pathAfterVersion === "/" || pathAfterVersion === ""
+            ? ""
+            : pathAfterVersion);
+
+        if (!localeRoutePaths.has(targetPath)) {
+          fallbackRoutes.push({
+            ...defRoute,
+            path: targetPath,
+            locale: locale,
+          });
+        }
+      }
+    }
+
+    return sortRoutes([...routes, ...fallbackRoutes]);
+  }
+
+  return sortRoutes(routes);
+}

package/src/node/routes/parser.ts

@@ -1,127 +1,153 @@
-import path from "path";
-import GithubSlugger from "github-slugger";
-import { BoltdocsConfig } from "../config";
-import { ParsedDocFile } from "./types";
-import {
-  normalizePath,
-  parseFrontmatter,
-  fileToRoutePath,
-  capitalize,
-  stripNumberPrefix,
-  extractNumberPrefix,
-} from "../utils";
-
-/**
- * Parses a single Markdown/MDX file and extracts its metadata for routing.
- * Checks frontmatter for explicit titles, descriptions, and sidebar positions.
- *
- * @param file - The absolute path to the file
- * @param docsDir - The root documentation directory (e.g., 'docs')
- * @param basePath - The base URL path for the routes (default: '/docs')
- * @returns A parsed structure ready for route assembly and caching
- */
-export function parseDocFile(
-  file: string,
-  docsDir: string,
-  basePath: string,
-  config?: BoltdocsConfig,
-): ParsedDocFile {
-  const { data, content } = parseFrontmatter(file);
-  const relativePath = normalizePath(path.relative(docsDir, file));
-  let parts = relativePath.split("/");
-
-  let locale: string | undefined;
-  let version: string | undefined;
-
-  // Level 1: Check for version
-  if (config?.versions && parts.length > 0) {
-    const potentialVersion = parts[0];
-    if (config.versions.versions[potentialVersion]) {
-      version = potentialVersion;
-      parts = parts.slice(1);
-    }
-  }
-
-  // Level 2: Check for locale
-  if (config?.i18n && parts.length > 0) {
-    const potentialLocale = parts[0];
-    if (config.i18n.locales[potentialLocale]) {
-      locale = potentialLocale;
-      parts = parts.slice(1);
-    }
-  }
-
-  const cleanRelativePath = parts.join("/");
-  const cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
-
-  let finalPath = basePath;
-  if (version) {
-    finalPath += "/" + version;
-  }
-  if (locale) {
-    finalPath += "/" + locale;
-  }
-  finalPath += cleanRoutePath === "/" ? "" : cleanRoutePath;
-
-  if (!finalPath || finalPath === "") finalPath = "/";
-
-  const rawFileName = parts[parts.length - 1];
-  const cleanFileName = stripNumberPrefix(rawFileName);
-  const inferredTitle = stripNumberPrefix(
-    path.basename(file, path.extname(file)),
-  );
-  const sidebarPosition =
-    data.sidebarPosition ?? extractNumberPrefix(rawFileName);
-
-  const rawDirName = parts.length >= 2 ? parts[0] : undefined;
-  const cleanDirName = rawDirName ? stripNumberPrefix(rawDirName) : undefined;
-
-  const isGroupIndex = parts.length >= 2 && /^index\.mdx?$/.test(cleanFileName);
-
-  const headings: { level: number; text: string; id: string }[] = [];
-  const slugger = new GithubSlugger();
-  const headingsRegex = /^(#{2,4})\s+(.+)$/gm;
-  let match;
-  while ((match = headingsRegex.exec(content)) !== null) {
-    const level = match[1].length;
-    // Strip simple markdown formatting specifically for the plain-text search index
-    const text = match[2]
-      .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1")
-      .replace(/[_*`]/g, "")
-      .trim();
-    const id = slugger.slug(text);
-    headings.push({ level, text, id });
-  }
-
-  return {
-    route: {
-      path: finalPath,
-      componentPath: file,
-      filePath: relativePath,
-      title: data.title || inferredTitle,
-      description: data.description || "",
-      sidebarPosition,
-      headings,
-      locale,
-      version,
-      badge: data.badge,
-    },
-    relativeDir: cleanDirName,
-    isGroupIndex,
-    groupMeta: isGroupIndex
-      ? {
-          title:
-            data.groupTitle ||
-            data.title ||
-            (cleanDirName ? capitalize(cleanDirName) : ""),
-          position:
-            data.groupPosition ??
-            data.sidebarPosition ??
-            (rawDirName ? extractNumberPrefix(rawDirName) : undefined),
-        }
-      : undefined,
-    inferredGroupPosition: rawDirName
-      ? extractNumberPrefix(rawDirName)
-      : undefined,
-  };
-}
+import path from "path";
+import GithubSlugger from "github-slugger";
+import { BoltdocsConfig } from "../config";
+import { ParsedDocFile } from "./types";
+import {
+  normalizePath,
+  parseFrontmatter,
+  fileToRoutePath,
+  capitalize,
+  stripNumberPrefix,
+  extractNumberPrefix,
+  escapeHtml,
+} from "../utils";
+
+/**
+ * Parses a single Markdown/MDX file and extracts its metadata for routing.
+ * Checks frontmatter for explicit titles, descriptions, and sidebar positions.
+ *
+ * @param file - The absolute path to the file
+ * @param docsDir - The root documentation directory (e.g., 'docs')
+ * @param basePath - The base URL path for the routes (default: '/docs')
+ * @returns A parsed structure ready for route assembly and caching
+ */
+export function parseDocFile(
+  file: string,
+  docsDir: string,
+  basePath: string,
+  config?: BoltdocsConfig,
+): ParsedDocFile {
+  // Security: Prevent path traversal
+  const decodedFile = decodeURIComponent(file);
+  const absoluteFile = path.resolve(decodedFile);
+  const absoluteDocsDir = path.resolve(docsDir);
+  const relativePath = normalizePath(
+    path.relative(absoluteDocsDir, absoluteFile),
+  );
+
+  if (
+    relativePath.startsWith("../") ||
+    relativePath === ".." ||
+    absoluteFile.includes("\0")
+  ) {
+    throw new Error(
+      `Security breach: File is outside of docs directory or contains null bytes: ${file}`,
+    );
+  }
+
+  const { data, content } = parseFrontmatter(file);
+  let parts = relativePath.split("/");
+
+  let locale: string | undefined;
+  let version: string | undefined;
+
+  // Level 1: Check for version
+  if (config?.versions && parts.length > 0) {
+    const potentialVersion = parts[0];
+    if (config.versions.versions[potentialVersion]) {
+      version = potentialVersion;
+      parts = parts.slice(1);
+    }
+  }
+
+  // Level 2: Check for locale
+  if (config?.i18n && parts.length > 0) {
+    const potentialLocale = parts[0];
+    if (config.i18n.locales[potentialLocale]) {
+      locale = potentialLocale;
+      parts = parts.slice(1);
+    }
+  }
+
+  const cleanRelativePath = parts.join("/");
+  const cleanRoutePath = fileToRoutePath(cleanRelativePath || "index.md");
+
+  let finalPath = basePath;
+  if (version) {
+    finalPath += "/" + version;
+  }
+  if (locale) {
+    finalPath += "/" + locale;
+  }
+  finalPath += cleanRoutePath === "/" ? "" : cleanRoutePath;
+
+  if (!finalPath || finalPath === "") finalPath = "/";
+
+  const rawFileName = parts[parts.length - 1];
+  const cleanFileName = stripNumberPrefix(rawFileName);
+  const inferredTitle = stripNumberPrefix(
+    path.basename(file, path.extname(file)),
+  );
+  const sidebarPosition =
+    data.sidebarPosition ?? extractNumberPrefix(rawFileName);
+
+  const rawDirName = parts.length >= 2 ? parts[0] : undefined;
+  const cleanDirName = rawDirName ? stripNumberPrefix(rawDirName) : undefined;
+
+  const isGroupIndex = parts.length >= 2 && /^index\.mdx?$/.test(cleanFileName);
+
+  const headings: { level: number; text: string; id: string }[] = [];
+  const slugger = new GithubSlugger();
+  const headingsRegex = /^(#{2,4})\s+(.+)$/gm;
+  let match;
+  while ((match = headingsRegex.exec(content)) !== null) {
+    const level = match[1].length;
+    // Strip simple markdown formatting specifically for the plain-text search index
+    const text = match[2]
+      .replace(/\[([^\]]+)\]\([^\)]+\)/g, "$1")
+      .replace(/[_*`]/g, "")
+      .trim();
+    const id = slugger.slug(text);
+    // Security: Sanitize heading text for XSS
+    headings.push({ level, text: escapeHtml(text), id });
+  }
+
+  const sanitizedTitle = data.title ? escapeHtml(data.title) : inferredTitle;
+  const sanitizedDescription = data.description
+    ? escapeHtml(data.description)
+    : "";
+  const sanitizedBadge = data.badge ? escapeHtml(data.badge) : undefined;
+
+  return {
+    route: {
+      path: finalPath,
+      componentPath: file,
+      filePath: relativePath,
+      title: sanitizedTitle,
+      description: sanitizedDescription,
+      sidebarPosition,
+      headings,
+      locale,
+      version,
+      badge: sanitizedBadge,
+    },
+    relativeDir: cleanDirName,
+    isGroupIndex,
+    groupMeta: isGroupIndex
+      ? {
+          title: escapeHtml(
+            data.groupTitle ||
+              data.title ||
+              (cleanDirName ? capitalize(cleanDirName) : ""),
+          ),
+          position:
+            data.groupPosition ??
+            data.sidebarPosition ??
+            (rawDirName ? extractNumberPrefix(rawDirName) : undefined),
+        }
+      : undefined,
+    inferredGroupPosition: rawDirName
+      ? extractNumberPrefix(rawDirName)
+      : undefined,
+  };
+}