boltdocs 2.5.4 → 2.5.6

package/src/node/routes/parser.ts

@@ -1,262 +0,0 @@
-import path from 'path'
-import GithubSlugger from 'github-slugger'
-import type { BoltdocsConfig } from '../config'
-import type { ParsedDocFile } from './types'
-import {
-  normalizePath,
-  parseFrontmatter,
-  fileToRoutePath,
-  capitalize,
-  stripNumberPrefix,
-  extractNumberPrefix,
-  sanitizeHtml,
-  stripHtmlTags,
-  logSecurityEvent,
-} from '../utils'
-import { MAX_PATH_LENGTH, ALLOWED_PATH_CHARS } from '../security/constants'
-import { EncodingSecurityError, PathTraversalError } from '../errors'
-
-/**
- * Parses a single Markdown/MDX file and extracts its metadata for routing.
- * Checks frontmatter for explicit titles, descriptions, and sidebar positions.
- *
- * Also performs security validation to prevent path traversal and basic
- * XSS sanitization for metadata and headings.
- *
- * @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')
- * @param config - The Boltdocs configuration for versions and i18n
- * @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 and malicious encoding
-  let decodedFile: string
-  try {
-    decodedFile = decodeURIComponent(file)
-  } catch {
-    const fileName = path.basename(file)
-    logSecurityEvent('ENCODING_ERROR', 'Invalid character encoding', { file: fileName })
-    throw new EncodingSecurityError(
-      `Security breach: Invalid characters or encoding in path: ${fileName}`,
-    )
-  }
-
-  // Validation: Path length
-  if (decodedFile.length > MAX_PATH_LENGTH) {
-    const fileName = path.basename(decodedFile)
-    logSecurityEvent('PATH_TOO_LONG', 'Path length exceeds limit', {
-      length: decodedFile.length,
-      file: fileName,
-    })
-    throw new PathTraversalError(
-      `Security breach: Path length exceeds limit of ${MAX_PATH_LENGTH} characters: ${fileName}`,
-    )
-  }
-
-  const absoluteFile = path.resolve(decodedFile)
-  const absoluteDocsDir = path.resolve(docsDir)
-  const relativePath = normalizePath(
-    path.relative(absoluteDocsDir, absoluteFile),
-  )
-
-  if (
-    relativePath.startsWith('../') ||
-    relativePath === '..' ||
-    absoluteFile.includes('\0') ||
-    !ALLOWED_PATH_CHARS.test(relativePath)
-  ) {
-    const fileName = path.basename(file)
-    logSecurityEvent('PATH_TRAVERSAL_ATTEMPT', 'Path traversal or invalid characters detected', {
-      path: relativePath,
-    })
-    throw new PathTraversalError(
-      `Security breach: File is outside of docs directory, contains null bytes, or invalid characters: ${fileName}`,
-    )
-  }
-
-  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]
-    const prefix = config.versions.prefix || ''
-
-    const versionMatch = config.versions.versions.find((v) => {
-      const fullPath = prefix + v.path
-      return potentialVersion === fullPath || potentialVersion === v.path
-    })
-
-    if (versionMatch) {
-      version = versionMatch.path
-      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)
-    }
-  }
-
-  // Level 3: Check for Tab hierarchy (name)
-  let inferredTab: string | undefined
-  if (parts.length > 0) {
-    const tabMatch = parts[0].match(/^\((.+)\)$/)
-    if (tabMatch) {
-      inferredTab = tabMatch[1].toLowerCase()
-      parts = parts.slice(1)
-    }
-  }
-
-  const cleanRelativePath = parts.join('/')
-
-  let cleanRoutePath: string
-  if (data.permalink) {
-    // If a permalink is specified, ensure it starts with a slash
-    cleanRoutePath = data.permalink.startsWith('/')
-      ? data.permalink
-      : `/${data.permalink}`
-  } else {
-    cleanRoutePath = fileToRoutePath(cleanRelativePath || 'index.md')
-  }
-
-  let finalPath = basePath
-  if (version) {
-    finalPath += '/' + version
-  }
-  if (locale) {
-    finalPath += '/' + locale
-  }
-  if (inferredTab) {
-    finalPath += '/' + inferredTab
-  }
-  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 slugger = new GithubSlugger()
-  const headings: { level: number; text: string; id: string }[] = []
-  const headingsRegex = /^(#{2,4})\s+(.+)$/gm
-
-  for (const match of content.matchAll(headingsRegex)) {
-    const level = match[1].length
-    const rawText = match[2]
-      .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Strip markdown links
-      .replace(/[_*`]/g, '') // Strip markdown formatting
-      .trim()
-
-    const sanitizedText = sanitizeHtml(rawText).trim()
-    const id = slugger.slug(sanitizedText)
-
-    headings.push({ level, text: sanitizedText, id })
-  }
-
-  const sanitizedTitle = data.title
-    ? sanitizeHtml(String(data.title))
-    : inferredTitle
-  let sanitizedDescription = data.description
-    ? sanitizeHtml(String(data.description))
-    : ''
-
-  // If no description is provided, extract a summary from the content
-  if (!sanitizedDescription && content) {
-    const plainExcerpt = stripHtmlTags(
-      content
-        .replace(/^#+.*$/gm, '') // Remove headers
-        .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Simplify links
-        .replace(/[_*`]/g, '') // Remove formatting
-        .replace(/\s+/g, ' '), // Normalize whitespace
-    )
-      .trim()
-      .slice(0, 160)
-
-    sanitizedDescription = plainExcerpt
-  }
-
-  const sanitizedBadge = data.badge
-    ? sanitizeHtml(String(data.badge))
-    : undefined
-  const icon = data.icon ? String(data.icon) : undefined
-
-  // Extract full content as plain text for search indexing
-  const plainText = parseContentToPlainText(content)
-
-  return {
-    route: {
-      path: finalPath,
-      componentPath: file,
-      filePath: relativePath,
-      title: sanitizedTitle,
-      description: sanitizedDescription,
-      sidebarPosition,
-      headings,
-      locale,
-      version,
-      badge: sanitizedBadge,
-      icon,
-      tab: inferredTab,
-      _content: plainText,
-      _rawContent: content,
-    },
-    relativeDir: cleanDirName,
-    isGroupIndex,
-    inferredTab,
-    groupMeta: isGroupIndex
-      ? {
-          title:
-            data.groupTitle ||
-            data.title ||
-            (cleanDirName ? capitalize(cleanDirName) : ''),
-          position:
-            data.groupPosition ??
-            data.sidebarPosition ??
-            (rawDirName ? extractNumberPrefix(rawDirName) : undefined),
-          icon,
-        }
-      : undefined,
-    inferredGroupPosition: rawDirName
-      ? extractNumberPrefix(rawDirName)
-      : undefined,
-  }
-}
-
-/**
- * Converts markdown content to plain text for search indexing.
- * Strips headers, links, tags, and formatting.
- */
-function parseContentToPlainText(content: string): string {
-  const plainText = content
-    .replace(/^#+.*$/gm, '') // Remove headers
-    .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // Simplify links
-    .replace(/\{[^\}]+\}/g, '') // Remove JS expressions/curly braces
-    .replace(/[_*`]/g, '') // Remove formatting
-    .replace(/\s+/g, ' ') // Normalize whitespace
-
-  return stripHtmlTags(plainText).trim()
-}

package/src/node/routes/sorter.ts

@@ -1,42 +0,0 @@
-import type { 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,61 +0,0 @@
-/**
- * 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
-  /** Optional icon for the route's group */
-  groupIcon?: string
-  /** 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 }
-  /** Optional icon to display (Lucide icon name or raw SVG) */
-  icon?: string
-  /** The tab this route belongs to, if tabs are configured */
-  tab?: string
-  /** The extracted plain-text content of the page for search indexing */
-  _content?: string
-  /** The raw markdown content of the page */
-  _rawContent?: 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; icon?: string }
-  /** Extracted group position from the directory name if it has a numeric prefix */
-  inferredGroupPosition?: number
-  /** Extracted tab name from the directory name if it follows the (tab-name) syntax */
-  inferredTab?: string
-}

package/src/node/schema/config.ts

@@ -1,195 +0,0 @@
-import { z } from 'zod'
-
-/**
- * Zod schema for a single social link.
- */
-export const SocialLinkSchema = z.object({
-  icon: z.string().max(50),
-  link: z.string().url(),
-})
-
-/**
- * Zod schema for footer configuration.
- */
-export const FooterConfigSchema = z.object({
-  text: z.string().max(2000).optional(),
-})
-
-/**
- * Zod schema for plugin permissions.
- */
-export const PluginPermissionSchema = z.enum([
-  'fs:read',
-  'fs:write',
-  'vite:config',
-  'mdx:remark',
-  'mdx:rehype',
-  'components',
-  'hooks:build',
-  'hooks:dev',
-])
-
-/**
- * Zod schema for a Boltdocs plugin.
- */
-export const BoltdocsPluginSchema = z.object({
-  name: z.string(),
-  enforce: z.enum(['pre', 'post']).optional(),
-  version: z.string().optional(),
-  boltdocsVersion: z.string().optional(),
-  permissions: z.array(PluginPermissionSchema).optional(),
-  remarkPlugins: z.array(z.any()).optional(),
-  rehypePlugins: z.array(z.any()).optional(),
-  vitePlugins: z.array(z.any()).optional(),
-  components: z.record(z.string(), z.string()).optional(),
-  hooks: z.record(z.string(), z.any()).optional(),
-})
-
-/**
- * Zod schema for theme configuration.
- */
-export const ThemeConfigSchema = z.object({
-  title: z.union([z.string(), z.record(z.string(), z.string())]).optional(),
-  description: z.union([z.string(), z.record(z.string(), z.string())]).optional(),
-  logo: z
-    .union([
-      z.string(),
-      z.object({
-        dark: z.string(),
-        light: z.string(),
-        alt: z.string().optional(),
-        width: z.number().optional(),
-        height: z.number().optional(),
-      }),
-    ])
-    .optional(),
-  navbar: z
-    .array(
-      z.object({
-        label: z.union([z.string(), z.record(z.string(), z.string())]),
-        href: z.string(),
-      }),
-    )
-    .optional(),
-  sidebar: z
-    .record(
-      z.string(),
-      z.array(
-        z.object({
-          text: z.string(),
-          link: z.string(),
-        }),
-      ),
-    )
-    .optional(),
-  socialLinks: z.array(SocialLinkSchema).optional(),
-  footer: FooterConfigSchema.optional(),
-  breadcrumbs: z.boolean().optional(),
-  editLink: z.string().refine(val => !val || val.includes(':path'), {
-    message: "editLink must contain ':path' placeholder if specified"
-  }).optional(),
-  communityHelp: z.string().url().optional(),
-  version: z.string().max(50).optional(),
-  githubRepo: z.string().max(100).optional(),
-  favicon: z.string().optional(),
-  ogImage: z.string().optional(),
-  poweredBy: z.boolean().optional(),
-  tabs: z
-    .array(
-      z.object({
-        id: z.string(),
-        text: z.union([z.string(), z.record(z.string(), z.string())]),
-        icon: z.string().optional(),
-      }),
-    )
-    .optional(),
-  codeTheme: z
-    .union([z.string(), z.object({ light: z.string(), dark: z.string() })])
-    .optional(),
-  copyMarkdown: z
-    .union([
-      z.boolean(),
-      z.object({
-        text: z.string().optional(),
-        icon: z.string().optional(),
-      }),
-    ])
-    .optional(),
-})
-
-/**
- * Zod schema for robots.txt configuration.
- */
-export const RobotsConfigSchema = z.union([
-  z.string(),
-  z.object({
-    rules: z
-      .array(
-        z.object({
-          userAgent: z.string(),
-          allow: z.union([z.string(), z.array(z.string())]).optional(),
-          disallow: z.union([z.string(), z.array(z.string())]).optional(),
-        }),
-      )
-      .optional(),
-    sitemaps: z.array(z.string().url()).optional(),
-  }),
-])
-
-/**
- * Zod schema for internationalization configuration.
- */
-export const I18nConfigSchema = z.object({
-  defaultLocale: z.string(),
-  locales: z.record(z.string(), z.string()),
-  localeConfigs: z
-    .record(
-      z.string(),
-      z.object({
-        label: z.string().optional(),
-        direction: z.enum(['ltr', 'rtl']).optional(),
-        htmlLang: z.string().optional(),
-        calendar: z.string().optional(),
-      }),
-    )
-    .optional(),
-})
-
-/**
- * Zod schema for versioning configuration.
- */
-export const VersionsConfigSchema = z.object({
-  defaultVersion: z.string(),
-  prefix: z.string().optional(),
-  versions: z.array(
-    z.object({
-      label: z.string(),
-      path: z.string(),
-    }),
-  ),
-})
-
-/**
- * Zod schema for security configuration.
- */
-export const SecurityConfigSchema = z.object({
-  headers: z.record(z.string(), z.string()).optional(),
-  enableCSP: z.boolean().optional(),
-  customHeaders: z.record(z.string(), z.string()).optional(),
-})
-
-/**
- * Root Zod schema for Boltdocs project configuration.
- */
-export const BoltdocsConfigSchema = z.object({
-  siteUrl: z.string().url().optional(),
-  docsDir: z.string().optional(),
-  homePage: z.string().optional(),
-  theme: ThemeConfigSchema.optional(),
-  i18n: I18nConfigSchema.optional(),
-  versions: VersionsConfigSchema.optional(),
-  plugins: z.array(BoltdocsPluginSchema).optional(),
-  robots: RobotsConfigSchema.optional(),
-  security: SecurityConfigSchema.optional(),
-  vite: z.record(z.string(), z.unknown()).optional(),
-})

package/src/node/schema/frontmatter.ts

@@ -1,17 +0,0 @@
-import { z } from 'zod'
-
-/**
- * Schema for strict frontmatter validation.
- */
-export const FrontmatterSchema = z.object({
-  title: z.string().max(200).optional(),
-  description: z.string().max(500).optional(),
-  sidebarPosition: z.number().optional(),
-  sidebarLabel: z.string().max(100).optional(),
-  category: z.string().max(50).optional(),
-  order: z.number().optional(),
-  badge: z.string().max(50).optional(),
-  icon: z.string().max(50).optional(),
-})
-
-export type FrontmatterData = z.infer<typeof FrontmatterSchema>

package/src/node/search/index.ts

@@ -1,55 +0,0 @@
-import type { RouteMeta } from '../routes/types'
-
-export interface SearchDocument {
-  id: string
-  title: string
-  content: string
-  url: string
-  display: string
-  locale?: string
-  version?: string
-}
-
-/**
- * Generates a flat list of searchable documents from the route metadata.
- * Each page is indexed as a primary document, and its sections (headings)
- * are indexed as secondary documents to provide granular search results.
- */
-export function generateSearchData(routes: RouteMeta[]): SearchDocument[] {
-  const documents: SearchDocument[] = []
-
-  for (const route of routes) {
-    // 1. Index the main page
-    documents.push({
-      id: route.path,
-      title: route.title,
-      content: route._content || '',
-      url: route.path,
-      display: route.groupTitle
-        ? `${route.groupTitle} > ${route.title}`
-        : route.title,
-      locale: route.locale,
-      version: route.version,
-    })
-
-    // 2. Index headings as sub-documents for deep linking
-    if (route.headings) {
-      for (const heading of route.headings) {
-        // We find the content belonging to this heading?
-        // For now, indexing just the heading text and a bit of context is standard.
-        // Deep full-text mapping to specific headings is more complex.
-        documents.push({
-          id: `${route.path}#${heading.id}`,
-          title: heading.text,
-          content: `${heading.text} in ${route.title}`,
-          url: `${route.path}#${heading.id}`,
-          display: `${route.title} > ${heading.text}`,
-          locale: route.locale,
-          version: route.version,
-        })
-      }
-    }
-  }
-
-  return documents
-}

package/src/node/security/constants/index.ts

@@ -1,10 +0,0 @@
-/**
- * Security limits for file system operations.
- */
-export const MAX_PATH_LENGTH = 260
-export const ALLOWED_PATH_CHARS = /^[a-zA-Z0-9\-_\/\.\(\)]+$/
-
-/**
- * Security limits for document metadata (frontmatter).
- */
-export const MAX_FRONTMATTER_SIZE = 10 * 1024 // 10KB

package/src/node/security/csp.ts

@@ -1,31 +0,0 @@
-import type { BoltdocsConfig } from '../config'
-
-/**
- * Generates a Content Security Policy (CSP) header string based on the configuration.
- * Automatically adapts to the environment (development vs production).
- * 
- * @param config - The Boltdocs configuration object.
- * @returns The CSP header value.
- */
-export function getCSPHeader(_config: BoltdocsConfig): string {
-  const isDev = process.env.NODE_ENV === 'development'
-  
-  const directives: Record<string, string[]> = {
-    'default-src': ["'self'"],
-    'script-src': ["'self'", "'unsafe-inline'"],
-    'style-src': ["'self'", "'unsafe-inline'"],
-    'img-src': ["'self'", "data:", "https:"],
-    'font-src': ["'self'"],
-    'connect-src': ["'self'"],
-  }
-
-  // Relax policies in development to support Vite's HMR (eval-based)
-  if (isDev) {
-    directives['script-src'] = ["'self'", "'unsafe-eval'", "'unsafe-inline'"]
-    directives['style-src'] = ["'self'", "'unsafe-inline'"]
-  }
-
-  return Object.entries(directives)
-    .map(([key, values]) => `${key} ${values.join(' ')}`)
-    .join('; ')
-}