boltdocs 2.2.0 → 2.3.0

package/src/node/{cli.ts → cli/build.ts}

@@ -1,27 +1,16 @@
-import { createServer, build, preview } from 'vite'
-import { createViteConfig, resolveConfig } from './index'
-import { getHtmlTemplate } from './plugin/html'
+import { build, preview } from 'vite'
+import { createViteConfig, resolveConfig } from '../index'
+import { getHtmlTemplate } from '../plugin/html'
 import path from 'path'
 import fs from 'fs'
+import * as ui from './ui'
 
 /**
- * Core logic for the Boltdocs CLI commands.
- * These functions wrap Vite's JS API to provide a seamless experience.
+ * Logic for the `boltdocs build` command.
+ * Prepares the production bundle and handles dynamic index.html generation.
+ *
+ * @param root - The project root directory
  */
-
-export async function devAction(root: string = process.cwd()) {
-  try {
-    const viteConfig = await createViteConfig(root, 'development')
-    const server = await createServer(viteConfig)
-    await server.listen()
-    server.printUrls()
-    server.bindCLIShortcuts({ print: true })
-  } catch (e) {
-    console.error('[boltdocs] Failed to start dev server:', e)
-    process.exit(1)
-  }
-}
-
 export async function buildAction(root: string = process.cwd()) {
   let createdIndexHtml = false
   const indexPath = path.resolve(root, 'index.html')
@@ -35,9 +24,9 @@ export async function buildAction(root: string = process.cwd()) {
 
     const viteConfig = await createViteConfig(root, 'production')
     await build(viteConfig)
-    console.log('[boltdocs] Build completed successfully.')
+    ui.success('Build completed successfully.')
   } catch (e) {
-    console.error('[boltdocs] Build failed:', e)
+    ui.error('Build failed:', e)
     process.exit(1)
   } finally {
     if (createdIndexHtml && fs.existsSync(indexPath)) {
@@ -46,14 +35,19 @@ export async function buildAction(root: string = process.cwd()) {
   }
 }
 
+/**
+ * Logic for the `boltdocs preview` command.
+ * Serves the production build from the disk.
+ *
+ * @param root - The project root directory
+ */
 export async function previewAction(root: string = process.cwd()) {
   try {
     const viteConfig = await createViteConfig(root, 'production')
     const previewServer = await preview(viteConfig)
     previewServer.printUrls()
   } catch (e) {
-    console.error('[boltdocs] Failed to start preview server:', e)
+    ui.error('Failed to start preview server:', e)
     process.exit(1)
   }
 }
-

package/src/node/cli/dev.ts

@@ -0,0 +1,22 @@
+import { createServer } from 'vite'
+import { createViteConfig } from '../index'
+import * as ui from './ui'
+
+/**
+ * Logic for the `boltdocs dev` command.
+ * Starts a Vite development server and sets up HMR.
+ *
+ * @param root - The project root directory
+ */
+export async function devAction(root: string = process.cwd()) {
+  try {
+    const viteConfig = await createViteConfig(root, 'development')
+    const server = await createServer(viteConfig)
+    await server.listen()
+    server.printUrls()
+    server.bindCLIShortcuts({ print: true })
+  } catch (e) {
+    ui.error('Failed to start dev server:', e)
+    process.exit(1)
+  }
+}

package/src/node/cli/doctor.ts

@@ -0,0 +1,243 @@
+import path from 'path'
+import fs from 'fs'
+import fastGlob from 'fast-glob'
+import { resolveConfig } from '../config'
+import { parseFrontmatter, normalizePath } from '../utils'
+import * as ui from './ui'
+
+/**
+ * Interface representing a documentation hygiene issue.
+ */
+interface Issue {
+  level: 'high' | 'warning' | 'low'
+  message: string
+  suggestion?: string
+}
+
+/**
+ * Logic for the `boltdocs doctor` command.
+ * Scans the documentation directory for broken links, missing frontmatter,
+ * and orphaned translations.
+ *
+ * @param root - The project root directory
+ */
+export async function doctorAction(root: string = process.cwd()) {
+  const { colors } = ui
+  ui.info(
+    `${colors.bold}Running documentation health check...${colors.reset}\n`,
+  )
+  const start = performance.now()
+
+  try {
+    const config = await resolveConfig('docs', root)
+    const docsDir = path.resolve(root, 'docs')
+
+    if (!fs.existsSync(docsDir)) {
+      ui.error(`Documentation directory not found at ${docsDir}`)
+      process.exit(1)
+    }
+
+    const files = await fastGlob(['**/*.md', '**/*.mdx'], {
+      cwd: docsDir,
+      absolute: true,
+      suppressErrors: true,
+    })
+
+    let highCount = 0
+    let warningCount = 0
+    let lowCount = 0
+    const issuesMap = new Map<string, Issue[]>()
+
+    const addIssue = (file: string, issue: Issue) => {
+      const relPath = path.relative(docsDir, file)
+      let issues = issuesMap.get(relPath)
+      if (!issues) {
+        issues = []
+        issuesMap.set(relPath, issues)
+      }
+      issues.push(issue)
+      if (issue.level === 'high') highCount++
+      else if (issue.level === 'warning') warningCount++
+      else if (issue.level === 'low') lowCount++
+    }
+
+    const basePath = '/docs'
+
+    // 1. Scan for Frontmatter, Links, and Content Issues
+    for (const file of files) {
+      const { data, content } = parseFrontmatter(file)
+
+      // Frontmatter Validation
+      if (!data.title) {
+        addIssue(file, {
+          level: 'warning',
+          message: 'Missing "title" in frontmatter.',
+          suggestion:
+            'Add `title: Your Title` to the YAML frontmatter at the top of the file.',
+        })
+      }
+
+      if (!data.description) {
+        addIssue(file, {
+          level: 'low',
+          message: 'Missing "description" in frontmatter.',
+          suggestion:
+            'Adding a description helps with SEO and search previews.',
+        })
+      }
+
+      // Link Validation
+      const linkRegex = /\[.*?\]\((.*?)\)/g
+      const htmlLinkRegex = /<a\s+[^>]*href=["']([^"']+)["'][^>]*>/g
+      const links = [
+        ...content.matchAll(linkRegex),
+        ...content.matchAll(htmlLinkRegex),
+      ]
+
+      for (const match of links) {
+        let link = match[1]
+        if (
+          !link ||
+          link.startsWith('http') ||
+          link.startsWith('https') ||
+          link.startsWith('#') ||
+          link.startsWith('mailto:') ||
+          link.startsWith('tel:')
+        ) {
+          continue
+        }
+
+        link = link.split('#')[0]
+        if (!link) continue
+
+        let targetPath: string
+        if (link.startsWith('/')) {
+          let pathAfterBase = link
+          if (link.startsWith(basePath + '/') || link === basePath) {
+            pathAfterBase = link.substring(basePath.length)
+          }
+          targetPath = path.join(docsDir, pathAfterBase)
+        } else {
+          targetPath = path.resolve(path.dirname(file), link)
+        }
+
+        const extensions = ['', '.md', '.mdx', '/index.md', '/index.mdx']
+        let exists = false
+        for (const ext of extensions) {
+          const finalPath = targetPath + ext
+          if (fs.existsSync(finalPath) && fs.statSync(finalPath).isFile()) {
+            exists = true
+            break
+          }
+        }
+
+        if (!exists) {
+          addIssue(file, {
+            level: 'high',
+            message: `Broken internal link: "${link}"`,
+            suggestion: `Ensure the file exists at "${targetPath}". If it's a directory, ensure it has an "index.md" or "index.mdx".`,
+          })
+        }
+      }
+    }
+
+    // 2. Scan for Orphaned Translations
+    if (config.i18n) {
+      const { defaultLocale, locales } = config.i18n
+      const otherLocales = Object.keys(locales).filter(
+        (l) => l !== defaultLocale,
+      )
+
+      for (const file of files) {
+        const relPath = normalizePath(path.relative(docsDir, file))
+        const parts = relPath.split('/')
+
+        if (parts[0] === defaultLocale) {
+          const pathAfterLocale = parts.slice(1).join('/')
+          for (const locale of otherLocales) {
+            const localeParts = [locale, ...parts.slice(1)]
+            const targetLocaleFile = path.join(docsDir, ...localeParts)
+
+            if (!fs.existsSync(targetLocaleFile)) {
+              addIssue(file, {
+                level: 'warning',
+                message: `Missing translation for locale "${locale}"`,
+                suggestion: `Create a translated version of this file at "${locale}/${pathAfterLocale}".`,
+              })
+            }
+          }
+        }
+      }
+    }
+
+    // Final Reporting
+    if (issuesMap.size === 0) {
+      ui.success('All documentation files are healthy!\n')
+    } else {
+      for (const [file, issues] of issuesMap.entries()) {
+        console.log(`📄 ${colors.bold}${file}${colors.reset}`)
+
+        const sortedIssues = issues.sort((a, b) => {
+          const order = { high: 1, warning: 2, low: 3 }
+          return order[a.level] - order[b.level]
+        })
+
+        for (const issue of sortedIssues) {
+          let prefix = ''
+          let color = ''
+          if (issue.level === 'high') {
+            prefix = '❌'
+            color = colors.red
+          } else if (issue.level === 'warning') {
+            prefix = '⚠️'
+            color = colors.yellow
+          } else {
+            prefix = 'ℹ️'
+            color = colors.cyan
+          }
+
+          console.log(
+            `   ${color}${prefix} ${issue.level.toUpperCase()}:${colors.reset} ${issue.message}`,
+          )
+          if (issue.suggestion) {
+            console.log(
+              `      ${colors.gray}💡 Suggestion: ${issue.suggestion}${colors.reset}`,
+            )
+          }
+        }
+        console.log('')
+      }
+
+      console.log(`${colors.bold}Summary:${colors.reset}`)
+      console.log(
+        `   ${colors.red}${highCount} high-level errors${colors.reset}`,
+      )
+      console.log(`   ${colors.yellow}${warningCount} warnings${colors.reset}`)
+      console.log(
+        `   ${colors.cyan}${lowCount} minor improvements${colors.reset}\n`,
+      )
+
+      if (highCount > 0) {
+        ui.error(
+          'HIGH ERROR: Fix these to ensure your documentation builds correctly.',
+        )
+      }
+      if (warningCount > 0 || lowCount > 0) {
+        ui.info(
+          'TIP: Address warnings and suggestions for premium quality docs.',
+        )
+      }
+      console.log('')
+    }
+
+    const duration = performance.now() - start
+    ui.info(`Finished in ${duration.toFixed(2)}ms\n`)
+
+    if (highCount > 0) {
+      process.exit(1)
+    }
+  } catch (e) {
+    ui.error('Failed to run doctor check:', e)
+    process.exit(1)
+  }
+}

package/src/node/cli/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Boltdocs CLI Actions Module.
+ * This module exports all command-line actions used by the Boltdocs tool.
+ */
+
+export * from './dev'
+export * from './build'
+export * from './doctor'
+export * from './ui'

package/src/node/cli/ui.ts

@@ -0,0 +1,54 @@
+/**
+ * ANSI Escape sequences for terminal coloring and styling.
+ * Used to provide a premium and consistent CLI experience.
+ */
+export const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+}
+
+/**
+ * Formats a message with the boltdocs prefix and provided styling.
+ *
+ * @param message - The content to log
+ * @param style - Optional ANSI style prefix
+ * @returns The formatted string
+ */
+export function formatLog(message: string, style: string = ''): string {
+  return `${style}${colors.bold}[boltdocs]${colors.reset} ${message}${colors.reset}`
+}
+
+/**
+ * Logs a standard informational message to the console.
+ *
+ * @param message - The message to display
+ */
+export function info(message: string) {
+  console.log(formatLog(message))
+}
+
+/**
+ * Logs an error message to the console with red styling.
+ *
+ * @param message - The error description
+ * @param error - Optional error object for stack tracing
+ */
+export function error(message: string, error?: any) {
+  console.error(formatLog(message, colors.red))
+  if (error) console.error(error)
+}
+
+/**
+ * Logs a success message to the console with green styling.
+ *
+ * @param message - The success description
+ */
+export function success(message: string) {
+  console.log(formatLog(message, colors.green))
+}

package/src/node/cli-entry.ts

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
-import cac from "cac";
-import { devAction, buildAction, previewAction } from "./cli";
+import cac from 'cac'
+import {
+  devAction,
+  buildAction,
+  previewAction,
+  doctorAction,
+} from './cli/index'
 
-const cli = cac("boltdocs");
+const cli = cac('boltdocs')
 
-cli
-  .command("[root]", "Start development server")
-  .alias("dev")
-  .action(devAction);
+cli.command('[root]', 'Start development server').alias('dev').action(devAction)
 
-cli
-  .command("build [root]", "Build for production")
-  .action(buildAction);
+cli.command('build [root]', 'Build for production').action(buildAction)
 
-cli
-  .command("preview [root]", "Preview production build")
-  .action(previewAction);
+cli.command('preview [root]', 'Preview production build').action(previewAction)
 
-cli.help();
+cli.command('doctor [root]', 'Check documentation health').action(doctorAction)
+
+cli.help()
 // This will be replaced at build time or package publishing, but hardcoded to 2.0.0 for now
-cli.version("2.0.0");
+cli.version('2.0.0')
 
-cli.parse();
+cli.parse()

package/src/node/config.ts

@@ -164,7 +164,7 @@ export interface BoltdocsVersionConfig {
 export interface BoltdocsVersionsConfig {
   /** The default version path (e.g., 'v2') */
   defaultVersion: string
-  /** 
+  /**
    * Optional prefix for all version paths (e.g., 'v').
    * If set to 'v', version '1.1' will be available at '/docs/v1.1'.
    */

package/src/node/plugin/entry.ts

@@ -19,7 +19,7 @@ export function generateEntryCode(
   const homeImport = options.homePage
     ? `import HomePage from '${normalizePath(options.homePage)}';`
     : ''
-  
+
   // Auto-import index.css if it exists
   const cssPath = path.resolve(process.cwd(), 'index.css')
   const cssImport = fs.existsSync(cssPath) ? "import './index.css';" : ''

package/src/node/plugin/index.ts

@@ -9,6 +9,7 @@ import type { BoltdocsPluginOptions } from './types'
 import { generateEntryCode } from './entry'
 import { injectHtmlMeta, getHtmlTemplate } from './html'
 import { generateRobotsTxt } from '../ssg/robots'
+import { generateSearchData } from '../search'
 import fs from 'fs'
 
 export * from './types'
@@ -108,13 +109,12 @@ export function boltdocsPlugin(
 
           // Improved check: If it's a doc route, serve HTML even if it has a dot (e.g. version 1.1)
           // We only skip if it has a known asset extension to prevent serving HTML for images/js/etc.
-          const isAsset = /\.(js|css|png|jpe?g|gif|svg|ico|webp|woff2?|ttf|otf|mp4|webm|ogg|mp3|wav|flac|aac|pdf|zip|gz|map|json)$/i.test(url)
+          const isAsset =
+            /\.(js|css|png|jpe?g|gif|svg|ico|webp|woff2?|ttf|otf|mp4|webm|ogg|mp3|wav|flac|aac|pdf|zip|gz|map|json)$/i.test(
+              url,
+            )
 
-          if (
-            accept.includes('text/html') &&
-            !isAsset &&
-            isDocRoute
-          ) {
+          if (accept.includes('text/html') && !isAsset && isDocRoute) {
             let html = getHtmlTemplate(config)
             html = injectHtmlMeta(html, config)
             html = await server.transformIndexHtml(req.url || '/', html)
@@ -197,8 +197,10 @@ export function boltdocsPlugin(
               invalidateRouteCache()
               // Re-resolve config as it might affect versions/routes
               config = await resolveConfig(docsDir)
-              
-              const configMod = server.moduleGraph.getModuleById('\0virtual:boltdocs-config')
+
+              const configMod = server.moduleGraph.getModuleById(
+                '\0virtual:boltdocs-config',
+              )
               if (configMod) server.moduleGraph.invalidateModule(configMod)
 
               server.ws.send({
@@ -219,7 +221,12 @@ export function boltdocsPlugin(
             // Regenerate and push to client
             // Optimization: generateRoutes is mostly incremental thanks to docCache
             // We only force a full disk scan on add/unlink events
-            const newRoutes = await generateRoutes(docsDir, config, '/docs', type !== 'change')
+            const newRoutes = await generateRoutes(
+              docsDir,
+              config,
+              '/docs',
+              type !== 'change',
+            )
 
             const routesMod = server.moduleGraph.getModuleById(
               '\0virtual:boltdocs-routes',
@@ -247,7 +254,8 @@ export function boltdocsPlugin(
           id === 'virtual:boltdocs-config' ||
           id === 'virtual:boltdocs-entry' ||
           id === 'virtual:boltdocs-mdx-components' ||
-          id === 'virtual:boltdocs-layout'
+          id === 'virtual:boltdocs-layout' ||
+          id === 'virtual:boltdocs-search'
         ) {
           return '\0' + id
         }
@@ -316,6 +324,12 @@ export default UserLayout;`
           return `import { DefaultLayout } from 'boltdocs/client';
 export default DefaultLayout;`
         }
+
+        if (id === '\0virtual:boltdocs-search') {
+          const routes = await generateRoutes(docsDir, config)
+          const searchData = generateSearchData(routes)
+          return `export default ${JSON.stringify(searchData, null, 2)};`
+        }
       },
 
       transformIndexHtml: {

package/src/node/routes/parser.ts

@@ -60,14 +60,12 @@ export function parseDocFile(
   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
-      }
-    )
-    
+
+    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)
@@ -168,7 +166,9 @@ export function parseDocFile(
     sanitizedDescription = plainExcerpt
   }
 
-  const sanitizedBadge = data.badge ? sanitizeHtml(String(data.badge)) : undefined
+  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

package/src/node/search/index.ts

@@ -0,0 +1,55 @@
+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/ssg/index.ts

@@ -48,14 +48,17 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
         __esModule: true,
         default: function SSG_Virtual_Layout(props: any) {
           try {
-            const client = originalRequire.apply(this, [path.resolve(_dirname, '../client/index.js')])
-            const Comp = client.DefaultLayout || (({ children }: any) => children)
+            const client = originalRequire.apply(this, [
+              path.resolve(_dirname, '../client/index.js'),
+            ])
+            const Comp =
+              client.DefaultLayout || (({ children }: any) => children)
             const React = originalRequire.apply(this, ['react'])
             return React.createElement(Comp, props)
           } catch (e) {
             return props.children
           }
-        }
+        },
       }
     }
     return originalRequire.apply(this, [id, ...args])
@@ -77,8 +80,10 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
   // Generate an HTML file for each route concurrently
   await Promise.all(
     routes.map(async (route) => {
-      const siteTitle = getTranslated(config?.theme?.title, route.locale) || 'Boltdocs'
-      const siteDescription = getTranslated(config?.theme?.description, route.locale) || ''
+      const siteTitle =
+        getTranslated(config?.theme?.title, route.locale) || 'Boltdocs'
+      const siteDescription =
+        getTranslated(config?.theme?.description, route.locale) || ''
       const pageTitle = `${route.title} | ${siteTitle}`
       const pageDescription = route.description || siteDescription
 
@@ -111,7 +116,10 @@ export async function generateStaticPages(options: SSGOptions): Promise<void> {
           'utf-8',
         )
       } catch (e: any) {
-        console.error(`[boltdocs] Error SSR rendering route ${route.path}:`, e ? e.stack || e : e)
+        console.error(
+          `[boltdocs] Error SSR rendering route ${route.path}:`,
+          e ? e.stack || e : e,
+        )
       }
     }),
   )