boltdocs 1.3.0 → 1.3.2

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,
+  };
+}

package/src/node/routes/sorter.ts

@@ -1,42 +1,42 @@
-import { RouteMeta } from "./types";
-
-/**
- * Sorts an array of generated routes.
- * Ungrouped items come first. Items within the same group are sorted by position, then alphabetically.
- * Groups are sorted relative to each other by their group position, then alphabetically.
- *
- * @param routes - The unsorted routes
- * @returns A new array of sorted routes suitable for sidebar generation
- */
-export function sortRoutes(routes: RouteMeta[]): RouteMeta[] {
-  return routes.sort((a, b) => {
-    // Ungrouped first
-    if (!a.group && !b.group) return compareByPosition(a, b);
-    if (!a.group) return -1;
-    if (!b.group) return 1;
-
-    // Different groups: sort by group position
-    if (a.group !== b.group) {
-      return compareByGroupPosition(a, b);
-    }
-
-    // Same group: sort by item position
-    return compareByPosition(a, b);
-  });
-}
-
-function compareByPosition(a: RouteMeta, b: RouteMeta): number {
-  if (a.sidebarPosition !== undefined && b.sidebarPosition !== undefined)
-    return a.sidebarPosition - b.sidebarPosition;
-  if (a.sidebarPosition !== undefined) return -1;
-  if (b.sidebarPosition !== undefined) return 1;
-  return a.title.localeCompare(b.title);
-}
-
-function compareByGroupPosition(a: RouteMeta, b: RouteMeta): number {
-  if (a.groupPosition !== undefined && b.groupPosition !== undefined)
-    return a.groupPosition - b.groupPosition;
-  if (a.groupPosition !== undefined) return -1;
-  if (b.groupPosition !== undefined) return 1;
-  return (a.groupTitle || a.group!).localeCompare(b.groupTitle || b.group!);
-}
+import { RouteMeta } from "./types";
+
+/**
+ * Sorts an array of generated routes.
+ * Ungrouped items come first. Items within the same group are sorted by position, then alphabetically.
+ * Groups are sorted relative to each other by their group position, then alphabetically.
+ *
+ * @param routes - The unsorted routes
+ * @returns A new array of sorted routes suitable for sidebar generation
+ */
+export function sortRoutes(routes: RouteMeta[]): RouteMeta[] {
+  return routes.sort((a, b) => {
+    // Ungrouped first
+    if (!a.group && !b.group) return compareByPosition(a, b);
+    if (!a.group) return -1;
+    if (!b.group) return 1;
+
+    // Different groups: sort by group position
+    if (a.group !== b.group) {
+      return compareByGroupPosition(a, b);
+    }
+
+    // Same group: sort by item position
+    return compareByPosition(a, b);
+  });
+}
+
+function compareByPosition(a: RouteMeta, b: RouteMeta): number {
+  if (a.sidebarPosition !== undefined && b.sidebarPosition !== undefined)
+    return a.sidebarPosition - b.sidebarPosition;
+  if (a.sidebarPosition !== undefined) return -1;
+  if (b.sidebarPosition !== undefined) return 1;
+  return a.title.localeCompare(b.title);
+}
+
+function compareByGroupPosition(a: RouteMeta, b: RouteMeta): number {
+  if (a.groupPosition !== undefined && b.groupPosition !== undefined)
+    return a.groupPosition - b.groupPosition;
+  if (a.groupPosition !== undefined) return -1;
+  if (b.groupPosition !== undefined) return 1;
+  return (a.groupTitle || a.group!).localeCompare(b.groupTitle || b.group!);
+}

package/src/node/routes/types.ts

@@ -1,49 +1,49 @@
-/**
- * Metadata representing a single documentation route.
- * This information is used to build the client-side router and the sidebar navigation.
- */
-export interface RouteMeta {
-  /** The final URL path for the route (e.g., '/docs/guide/start') */
-  path: string;
-  /** The absolute filesystem path to the source markdown/mdx file */
-  componentPath: string;
-  /** The title of the page, usually extracted from frontmatter or the filename */
-  title: string;
-  /** The relative path from the docs directory, used for edit links */
-  filePath: string;
-  /** Optional description of the page (for SEO/meta tags) */
-  description?: string;
-  /** Optional explicit position for ordering in the sidebar */
-  sidebarPosition?: number;
-  /** The group (directory) this route belongs to */
-  group?: string;
-  /** The display title for the route's group */
-  groupTitle?: string;
-  /** Optional explicit position for ordering the group itself */
-  groupPosition?: number;
-  /** Extracted markdown headings for search indexing */
-  headings?: { level: number; text: string; id: string }[];
-  /** The locale this route belongs to, if i18n is configured */
-  locale?: string;
-  /** The version this route belongs to, if versioning is configured */
-  version?: string;
-  /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
-  badge?: string | { text: string; expires?: string };
-}
-
-/**
- * Internal representation of a parsed documentation file before finalizing groups.
- * Stored in the file cache to avoid re-parsing unchanged files.
- */
-export interface ParsedDocFile {
-  /** The core route metadata without group-level details (inferred later) */
-  route: Omit<RouteMeta, "group" | "groupTitle" | "groupPosition">;
-  /** The base directory of the file (used to group files together) */
-  relativeDir?: string;
-  /** Whether this file is the index file for its directory group */
-  isGroupIndex: boolean;
-  /** If this is a group index, any specific frontmatter metadata dictating the group's title and position */
-  groupMeta?: { title: string; position?: number };
-  /** Extracted group position from the directory name if it has a numeric prefix */
-  inferredGroupPosition?: number;
-}
+/**
+ * Metadata representing a single documentation route.
+ * This information is used to build the client-side router and the sidebar navigation.
+ */
+export interface RouteMeta {
+  /** The final URL path for the route (e.g., '/docs/guide/start') */
+  path: string;
+  /** The absolute filesystem path to the source markdown/mdx file */
+  componentPath: string;
+  /** The title of the page, usually extracted from frontmatter or the filename */
+  title: string;
+  /** The relative path from the docs directory, used for edit links */
+  filePath: string;
+  /** Optional description of the page (for SEO/meta tags) */
+  description?: string;
+  /** Optional explicit position for ordering in the sidebar */
+  sidebarPosition?: number;
+  /** The group (directory) this route belongs to */
+  group?: string;
+  /** The display title for the route's group */
+  groupTitle?: string;
+  /** Optional explicit position for ordering the group itself */
+  groupPosition?: number;
+  /** Extracted markdown headings for search indexing */
+  headings?: { level: number; text: string; id: string }[];
+  /** The locale this route belongs to, if i18n is configured */
+  locale?: string;
+  /** The version this route belongs to, if versioning is configured */
+  version?: string;
+  /** Optional badge to display next to the sidebar item (e.g., 'New', 'Experimental') */
+  badge?: string | { text: string; expires?: string };
+}
+
+/**
+ * Internal representation of a parsed documentation file before finalizing groups.
+ * Stored in the file cache to avoid re-parsing unchanged files.
+ */
+export interface ParsedDocFile {
+  /** The core route metadata without group-level details (inferred later) */
+  route: Omit<RouteMeta, "group" | "groupTitle" | "groupPosition">;
+  /** The base directory of the file (used to group files together) */
+  relativeDir?: string;
+  /** Whether this file is the index file for its directory group */
+  isGroupIndex: boolean;
+  /** If this is a group index, any specific frontmatter metadata dictating the group's title and position */
+  groupMeta?: { title: string; position?: number };
+  /** Extracted group position from the directory name if it has a numeric prefix */
+  inferredGroupPosition?: number;
+}