boltdocs 2.5.5 → 2.6.0

package/src/node/plugins/plugin-sandbox.ts

@@ -1,59 +0,0 @@
-import { PluginPermissionError } from './plugin-errors'
-import { hasPermission } from './plugin-validator'
-import type { SecureBoltdocsPlugin, PluginPermission } from './plugin-types'
-
-/**
- * The Sandbox provides a protective layer that ensures plugins only use
- * the capabilities they have explicitly requested permissions for.
- */
-export class PluginSandbox {
-  /**
-   * Validates if a plugin has the required permission for a capability.
-   * Throws a PluginPermissionError if not granted.
-   */
-  public static checkPermission(
-    plugin: SecureBoltdocsPlugin,
-    permission: PluginPermission
-  ): void {
-    if (!hasPermission(plugin, permission)) {
-      throw new PluginPermissionError(plugin.name, permission)
-    }
-  }
-
-  /**
-   * Filters a plugin's capabilities based on its declared permissions.
-   * This is used when aggregating plugins (remark, rehype, vite, components).
-   */
-  public static getSanitizedCapabilities(plugin: SecureBoltdocsPlugin) {
-    return {
-      remarkPlugins: hasPermission(plugin, 'mdx:remark') ? plugin.remarkPlugins : [],
-      rehypePlugins: hasPermission(plugin, 'mdx:rehype') ? plugin.rehypePlugins : [],
-      vitePlugins: hasPermission(plugin, 'vite:config') ? plugin.vitePlugins : [],
-      components: hasPermission(plugin, 'components') ? plugin.components : {},
-    }
-  }
-
-  /**
-   * Wraps a hook execution with permission checks and error isolation.
-   */
-  public static async executeWithIsolation<T>(
-    plugin: SecureBoltdocsPlugin,
-    requiredPermission: PluginPermission,
-    hookName: string,
-    action: () => Promise<T> | T
-  ): Promise<T | undefined> {
-    try {
-      this.checkPermission(plugin, requiredPermission)
-      return await action()
-    } catch (error) {
-      if (error instanceof PluginPermissionError) {
-        // Log skip instead of failing hard for permissions in some contexts
-        console.warn(`[boltdocs] Skipping hook '${hookName}' for plugin '${plugin.name}': ${error.message}`)
-        return undefined
-      }
-      
-      // Re-throw other errors to be caught by the LifecycleManager
-      throw error
-    }
-  }
-}

package/src/node/plugins/plugin-store.ts

@@ -1,54 +0,0 @@
-import type { PluginStore } from './plugin-types'
-
-/**
- * Implementation of the shared plugin store.
- * Uses a namespaced approach to prevent key collisions between plugins.
- */
-export class BoltdocsPluginStore implements PluginStore {
-  private data = new Map<string, unknown>()
-
-  /**
-   * Internal helper to create a namespaced key.
-   */
-  private getNamespaceKey(pluginName: string, key: string): string {
-    return `${pluginName}:${key}`
-  }
-
-  /**
-   * Retrieves a value from the store. Returns a deep clone to prevent mutations (side-effects).
-   */
-  public get<T = unknown>(pluginName: string, key: string): T | undefined {
-    const nsKey = this.getNamespaceKey(pluginName, key)
-    const value = this.data.get(nsKey)
-
-    if (value === undefined) return undefined
-
-    // For safety, return a deep clone if it's an object
-    if (typeof value === 'object' && value !== null) {
-      return JSON.parse(JSON.stringify(value)) as T
-    }
-
-    return value as T
-  }
-
-  /**
-   * Stores a value in the store. Key is automatically namespaced.
-   */
-  public set(pluginName: string, key: string, value: unknown): void {
-    const nsKey = this.getNamespaceKey(pluginName, key)
-    // We also store a clone to ensure the store state is immutable from the outside
-    const storedValue = typeof value === 'object' && value !== null 
-      ? JSON.parse(JSON.stringify(value)) 
-      : value
-    
-    this.data.set(nsKey, storedValue)
-  }
-
-  /**
-   * Checks for the existence of a key in the store.
-   */
-  public has(pluginName: string, key: string): boolean {
-    const nsKey = this.getNamespaceKey(pluginName, key)
-    return this.data.has(nsKey)
-  }
-}

package/src/node/plugins/plugin-types.ts

@@ -1,107 +0,0 @@
-import type { Plugin as VitePlugin } from 'vite'
-import type { BoltdocsConfig } from '../config'
-
-/**
- * Permissions that a plugin can request to access specific Boltdocs capabilities.
- */
-export type PluginPermission =
-  | 'fs:read'      // Read filesystem
-  | 'fs:write'     // Write filesystem
-  | 'vite:config'  // Modify Vite config
-  | 'mdx:remark'   // Add remark plugins
-  | 'mdx:rehype'   // Add rehype plugins
-  | 'components'   // Register MDX components
-  | 'hooks:build'  // Access build lifecycle hooks
-  | 'hooks:dev'    // Access dev lifecycle hooks
-
-/**
- * Shared context injected into every plugin lifecycle hook.
- */
-export interface PluginContext {
-  /** The full, resolved Boltdocs configuration (Readonly) */
-  readonly config: BoltdocsConfig
-  /** A plugin-specific logger */
-  readonly logger: PluginLogger
-  /** A shared store for dependency injection and state sharing between plugins */
-  readonly store: PluginStore
-  /** Metadata about the current plugin */
-  readonly meta: PluginMeta
-}
-
-/**
- * Simple logger interface for plugins.
- */
-export interface PluginLogger {
-  info(message: string): void
-  warn(message: string): void
-  error(message: string | Error): void
-  debug(message: string): void
-}
-
-/**
- * A shared key-value store that allows plugins to share state and configuration.
- */
-export interface PluginStore {
-  /** Get a value from the store. Keys are namespaced by plugin internally. */
-  get<T = unknown>(pluginName: string, key: string): T | undefined
-  /** Set a value in the store. */
-  set(pluginName: string, key: string, value: unknown): void
-  /** Check if a key exists in the store. */
-  has(pluginName: string, key: string): boolean
-}
-
-/**
- * Metadata for a plugin, used for identification and compatibility checks.
- */
-export interface PluginMeta {
-  /** Unique identifier for the plugin */
-  name: string
-  /** Version of the plugin itself (semver) */
-  version?: string
-  /** Minimum required version of Boltdocs (semver range) */
-  boltdocsVersion?: string
-}
-
-/**
- * Lifecycle hooks that a plugin can implement to hook into the build and dev processes.
- */
-export interface PluginLifecycleHooks {
-  /** Called before the build process starts */
-  beforeBuild?: (ctx: PluginContext) => Promise<void> | void
-  /** Called after the build process finishes successfully */
-  afterBuild?: (ctx: PluginContext) => Promise<void> | void
-  /** Called before the dev server starts */
-  beforeDev?: (ctx: PluginContext) => Promise<void> | void
-  /** Called after the dev server is ready (configureServer) */
-  afterDev?: (ctx: PluginContext) => Promise<void> | void
-  /** Called when the final Boltdocs config is resolved */
-  configResolved?: (ctx: PluginContext, config: BoltdocsConfig) => void
-  /** Called when the build is closing */
-  buildEnd?: (ctx: PluginContext) => Promise<void> | void
-}
-
-/**
- * The extended, secure Boltdocs plugin interface.
- */
-export interface SecureBoltdocsPlugin {
-  /** A unique name for the plugin (e.g., 'boltdocs-plugin-mermaid') */
-  name: string
-  /** Whether to run this plugin before or after default ones */
-  enforce?: 'pre' | 'post'
-  /** Version of the plugin (optional, but recommended for security) */
-  version?: string
-  /** Minimum compatible Boltdocs version (optional, semver range) */
-  boltdocsVersion?: string
-  /** List of permissions this plugin requires to operate */
-  permissions?: PluginPermission[]
-  /** Optional remark plugins to add to the MDX pipeline (requires 'mdx:remark' permission) */
-  remarkPlugins?: unknown[]
-  /** Optional rehype plugins to add to the MDX pipeline (requires 'mdx:rehype' permission) */
-  rehypePlugins?: unknown[]
-  /** Optional Vite plugins to inject into the build process (requires 'vite:config' permission) */
-  vitePlugins?: VitePlugin[]
-  /** Optional custom React components to register in MDX. Map of Name -> Module Path. (requires 'components' permission) */
-  components?: Record<string, string>
-  /** Implementation of lifecycle hooks (requires 'hooks:build' or 'hooks:dev' permissions) */
-  hooks?: PluginLifecycleHooks
-}

package/src/node/plugins/plugin-validator.ts

@@ -1,105 +0,0 @@
-import { z } from 'zod'
-import semver from 'semver'
-import path from 'path'
-import { BoltdocsPluginSchema } from '../schema/config'
-import {
-  PluginValidationError,
-  PluginCompatibilityError,
-} from './plugin-errors'
-import type { SecureBoltdocsPlugin, PluginPermission } from './plugin-types'
-
-/**
- * Enhanced Zod schema for secure plugins.
- */
-export const SecurePluginSchema = BoltdocsPluginSchema.extend({
-  version: z.string().optional(),
-  boltdocsVersion: z.string().optional(),
-  permissions: z.array(z.string()).optional(),
-  hooks: z
-    .object({
-      beforeBuild: z.function().optional(),
-      afterBuild: z.function().optional(),
-      beforeDev: z.function().optional(),
-      afterDev: z.function().optional(),
-      configResolved: z.function().optional(),
-      buildEnd: z.function().optional(),
-    })
-    .optional(),
-})
-
-/**
- * Validates a list of plugins for correctness, security, and compatibility.
- */
-export function validatePlugins(
-  plugins: any[],
-  boltdocsVersion: string,
-): SecureBoltdocsPlugin[] {
-  const validatedPlugins: SecureBoltdocsPlugin[] = []
-  const pluginNames = new Set<string>()
-
-  for (const rawPlugin of plugins) {
-    // 1. Basic Structure Validation
-    const result = SecurePluginSchema.safeParse(rawPlugin)
-    if (!result.success) {
-      throw new PluginValidationError(
-        rawPlugin.name || 'unknown',
-        result.error.issues
-          .map((i) => `${i.path.join('.')}: ${i.message}`)
-          .join(', '),
-      )
-    }
-
-    const plugin = result.data as SecureBoltdocsPlugin
-
-    // 2. Name Uniqueness
-    if (pluginNames.has(plugin.name)) {
-      throw new PluginValidationError(
-        plugin.name,
-        'Duplicate plugin name detected',
-      )
-    }
-    pluginNames.add(plugin.name)
-
-    // 3. Semver Compatibility
-    if (
-      plugin.boltdocsVersion &&
-      !semver.satisfies(boltdocsVersion, plugin.boltdocsVersion)
-    ) {
-      throw new PluginCompatibilityError(
-        plugin.name,
-        `Plugin expects Boltdocs version ${plugin.boltdocsVersion}, but current is ${boltdocsVersion}`,
-      )
-    }
-
-    // 4. Component Path Security (Path Traversal Prevention)
-    if (plugin.components) {
-      for (const [compName, compPath] of Object.entries(plugin.components)) {
-        if (compPath.includes('..') || path.isAbsolute(compPath)) {
-          // Absolute paths are technically okay but we restrict them for consistency/security
-          // if they point outside the workspace. For now, we block '..' explicitly.
-          if (compPath.includes('..')) {
-            throw new PluginValidationError(
-              plugin.name,
-              `Component '${compName}' has an invalid path: traversal sequences are not allowed.`,
-            )
-          }
-        }
-      }
-    }
-
-    validatedPlugins.push(plugin)
-  }
-
-  return validatedPlugins
-}
-
-/**
- * Helper to check if a specific permission is granted to a plugin.
- */
-export function hasPermission(
-  plugin: SecureBoltdocsPlugin,
-  permission: PluginPermission,
-): boolean {
-  if (!plugin.permissions) return false
-  return plugin.permissions.includes(permission)
-}

package/src/node/routes/cache.ts

@@ -1,28 +0,0 @@
-import { FileCache } from '../cache'
-import type { 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,293 +0,0 @@
-import fastGlob from 'fast-glob'
-import type { BoltdocsConfig } from '../config'
-import { capitalize } from '../utils'
-
-import type { 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 }
-
-// Cache for file list and localized path computations
-let cachedFileList: string[] | null = null
-const localizedPathCache = new Map<string, string>()
-
-/**
- * Generates the entire route map for the documentation site.
- * OPTIMIZED: Uses Map-based i18n lookups, chunked processing, and path caching.
- *
- * Automatically handles versioning and i18n routing, including fallback
- * generation for missing translations.
- *
- * @param docsDir - The root documentation directory
- * @param config - The Boltdocs configuration
- * @param basePath - The base URL path for the routes (default: '/docs')
- * @returns A promise resolving to an array of RouteMeta objects
- */
-export async function generateRoutes(
-  docsDir: string,
-  config?: BoltdocsConfig,
-  basePath: string = '/docs',
-  forceScan: boolean = true,
-): Promise<RouteMeta[]> {
-  const start = performance.now()
-
-  // Load persistent cache
-  docCache.load()
-
-  // Clear path computation cache between generations
-  localizedPathCache.clear()
-
-  // Force re-parse if specifically requested (e.g. for content/config changes)
-  if (process.env.BOLTDOCS_FORCE_REPARSE === 'true' || config?.i18n) {
-    docCache.invalidateAll()
-  }
-
-  // 1. FAST SCAN (Skip if incremental and we have a cache)
-  let files: string[]
-  if (!forceScan && cachedFileList) {
-    files = cachedFileList
-  } else {
-    files = await fastGlob(['**/*.md', '**/*.mdx'], {
-      cwd: docsDir,
-      absolute: true,
-      suppressErrors: true,
-      followSymbolicLinks: false,
-    })
-    cachedFileList = files
-  }
-
-  // Prune cache entries for deleted files
-  docCache.pruneStale(new Set(files))
-
-  // 2. CHUNKED PROCESSING (prevents blocking event loop)
-  const CHUNK_SIZE = 50
-  const parsed: ParsedDocFile[] = []
-  let cacheHits = 0
-
-  for (let i = 0; i < files.length; i += CHUNK_SIZE) {
-    const chunk = files.slice(i, i + CHUNK_SIZE)
-
-    const chunkResults = await Promise.all(
-      chunk.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
-      }),
-    )
-
-    parsed.push(...chunkResults)
-
-    // Yield to event loop between chunks if there's more to process
-    if (i + CHUNK_SIZE < files.length) {
-      await new Promise((resolve) => setImmediate(resolve))
-    }
-  }
-
-  // Save cache after processing
-  docCache.save()
-
-  // 3. OPTIMIZED METADATA COLLECTION
-  const groupMeta = new Map<
-    string,
-    { title: string; position?: number; icon?: string }
-  >()
-  const groupIndexFiles: ParsedDocFile[] = []
-
-  for (const p of parsed) {
-    if (p.isGroupIndex && p.relativeDir) {
-      groupIndexFiles.push(p)
-    }
-
-    if (p.relativeDir) {
-      let entry = groupMeta.get(p.relativeDir)
-      if (!entry) {
-        entry = {
-          title: capitalize(p.relativeDir),
-          position: p.inferredGroupPosition,
-          icon: p.route.icon,
-        }
-        groupMeta.set(p.relativeDir, entry)
-      } else {
-        if (
-          entry.position === undefined &&
-          p.inferredGroupPosition !== undefined
-        ) {
-          entry.position = p.inferredGroupPosition
-        }
-        if (!entry.icon && p.route.icon) {
-          entry.icon = p.route.icon
-        }
-      }
-    }
-  }
-
-  // Override with explicit group index metadata
-  for (const p of groupIndexFiles) {
-    const entry = groupMeta.get(p.relativeDir!)!
-    if (p.groupMeta) {
-      entry.title = p.groupMeta.title
-      if (p.groupMeta.position !== undefined)
-        entry.position = p.groupMeta.position
-      if (p.groupMeta.icon) entry.icon = p.groupMeta.icon
-    }
-  }
-
-  // 4. BUILD BASE ROUTES
-  const routes: RouteMeta[] = new Array(parsed.length)
-  for (let i = 0; i < parsed.length; i++) {
-    const p = parsed[i]
-    const dir = p.relativeDir
-    const meta = dir ? groupMeta.get(dir) : undefined
-
-    routes[i] = {
-      ...p.route,
-      group: dir,
-      groupTitle: meta?.title || (dir ? capitalize(dir) : undefined),
-      groupPosition: meta?.position,
-      groupIcon: meta?.icon,
-    }
-  }
-
-  // 5. OPTIMIZED I18N FALLBACKS
-  let finalRoutes = routes
-  if (config?.i18n) {
-    const fallbacks = generateI18nFallbacks(routes, config, basePath)
-    finalRoutes = [...routes, ...fallbacks]
-  }
-
-  const sorted = sortRoutes(finalRoutes)
-
-  const duration = performance.now() - start
-  console.log(
-    `[boltdocs] Route generation: ${duration.toFixed(2)}ms (${files.length} files, ${cacheHits} cache hits)`,
-  )
-
-  return sorted
-}
-
-/**
- * Generates fallback routes for missing translations.
- * Optimization: Uses Map for O(1) existence checks instead of nested filters.
- */
-function generateI18nFallbacks(
-  routes: RouteMeta[],
-  config: BoltdocsConfig,
-  basePath: string,
-): RouteMeta[] {
-  const defaultLocale = config.i18n!.defaultLocale
-  const allLocales = Object.keys(config.i18n!.locales)
-  const fallbackRoutes: RouteMeta[] = []
-
-  // Index existing routes by locale for O(1) lookup
-  const routesByLocale = new Map<string, Set<string>>()
-  const defaultRoutes: RouteMeta[] = []
-
-  for (const r of routes) {
-    const locale = r.locale || defaultLocale
-    if (!routesByLocale.has(locale)) {
-      routesByLocale.set(locale, new Set())
-    }
-    routesByLocale.get(locale)!.add(r.path)
-
-    if (locale === defaultLocale) {
-      defaultRoutes.push(r)
-    }
-  }
-
-  for (const locale of allLocales) {
-    const localePaths = routesByLocale.get(locale) || new Set<string>()
-
-    for (const defRoute of defaultRoutes) {
-      const targetPath = computeLocalizedPath(
-        defRoute.path,
-        defaultLocale,
-        locale,
-        basePath,
-        config,
-      )
-
-      // Skip if the path is already the same (e.g. for default locale unprefixed)
-      if (targetPath === defRoute.path) continue
-
-      if (!localePaths.has(targetPath)) {
-        fallbackRoutes.push({
-          ...defRoute,
-          path: targetPath,
-          locale,
-        })
-      }
-    }
-  }
-
-  return fallbackRoutes
-}
-
-/**
- * Computes a localized path based on the default locale and target locale.
- * Uses a cache to avoid redundant string manipulation.
- */
-function computeLocalizedPath(
-  path: string,
-  defaultLocale: string,
-  targetLocale: string,
-  basePath: string,
-  config?: BoltdocsConfig,
-): string {
-  const cacheKey = `${path}:${targetLocale}`
-  const cached = localizedPathCache.get(cacheKey)
-  if (cached) return cached
-
-  let prefix = basePath
-  if (config?.versions) {
-    const vPrefix = config.versions.prefix || ''
-    for (const vConfig of config.versions.versions) {
-      const fullVPath = vPrefix + vConfig.path
-      if (path.startsWith(`${basePath}/${fullVPath}`)) {
-        prefix += '/' + fullVPath
-        break
-      }
-      if (path.startsWith(`${basePath}/${vConfig.path}`)) {
-        prefix += '/' + vConfig.path
-        break
-      }
-    }
-  }
-
-  let pathAfterVersion = path.substring(prefix.length)
-
-  // Handle case where path already has default locale
-  const defaultLocaleSegment = `/${defaultLocale}`
-  if (pathAfterVersion.startsWith(defaultLocaleSegment + '/')) {
-    pathAfterVersion =
-      '/' +
-      targetLocale +
-      '/' +
-      pathAfterVersion.substring(defaultLocaleSegment.length + 1)
-  } else if (pathAfterVersion === defaultLocaleSegment) {
-    pathAfterVersion = '/' + targetLocale
-  } else if (pathAfterVersion === '/' || pathAfterVersion === '') {
-    pathAfterVersion = '/' + targetLocale
-  } else {
-    // Ensure pathAfterVersion starts with a slash if not already
-    const pathPrefix = pathAfterVersion.startsWith('/') ? '' : '/'
-    pathAfterVersion = '/' + targetLocale + pathPrefix + pathAfterVersion
-  }
-
-  const result = prefix + pathAfterVersion
-
-  // Simple cache eviction to prevent memory leaks in extreme cases
-  if (localizedPathCache.size > 2000) localizedPathCache.clear()
-  localizedPathCache.set(cacheKey, result)
-
-  return result
-}