@brainfish-ai/devdoc 0.1.21

package/renderer/lib/docs/mdx/compiler.ts

@@ -0,0 +1,176 @@
+import { compileMDX } from 'next-mdx-remote/rsc'
+import matter from 'gray-matter'
+import rehypeSlug from 'rehype-slug'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
+import remarkGfm from 'remark-gfm'
+import { parseFrontmatter, safeParseFrontmatter, type Frontmatter } from './frontmatter'
+
+/**
+ * MDX Compiler Utilities
+ * 
+ * Provides functions for compiling MDX content with custom components
+ * and extracting frontmatter metadata
+ */
+
+export interface MDXCompileResult<TFrontmatter = Frontmatter> {
+  content: React.ReactElement
+  frontmatter: TFrontmatter
+  headings: TableOfContentsItem[]
+}
+
+export interface TableOfContentsItem {
+  id: string
+  title: string
+  level: number
+}
+
+export interface CompileMDXOptions {
+  components?: Record<string, React.ComponentType<unknown>>
+  scope?: Record<string, unknown>
+  validateFrontmatter?: boolean
+}
+
+/**
+ * Extract frontmatter from raw MDX content
+ */
+export function extractFrontmatter(source: string): { 
+  content: string
+  data: Record<string, unknown>
+} {
+  const { content, data } = matter(source)
+  return { content, data }
+}
+
+/**
+ * Extract headings from MDX content for table of contents
+ */
+export function extractHeadings(content: string): TableOfContentsItem[] {
+  const headingRegex = /^(#{1,6})\s+(.+)$/gm
+  const headings: TableOfContentsItem[] = []
+  let match
+  
+  while ((match = headingRegex.exec(content)) !== null) {
+    const level = match[1].length
+    const title = match[2].trim()
+    // Generate slug from title (same logic as rehype-slug)
+    const id = title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+    
+    headings.push({ id, title, level })
+  }
+  
+  return headings
+}
+
+/**
+ * Compile MDX content with components and plugins
+ */
+export async function compileMDXContent<TFrontmatter = Frontmatter>(
+  source: string,
+  options: CompileMDXOptions = {}
+): Promise<MDXCompileResult<TFrontmatter>> {
+  const { components = {}, scope = {}, validateFrontmatter = true } = options
+  
+  // Extract frontmatter first
+  const { content: mdxContent, data: rawFrontmatter } = extractFrontmatter(source)
+  
+  // Validate frontmatter if requested
+  const frontmatter = validateFrontmatter 
+    ? parseFrontmatter(rawFrontmatter) as TFrontmatter
+    : rawFrontmatter as TFrontmatter
+  
+  // Extract headings for ToC
+  const headings = extractHeadings(mdxContent)
+  
+  // Compile MDX
+  const { content } = await compileMDX({
+    source: mdxContent,
+    components,
+    options: {
+      parseFrontmatter: false, // Already extracted
+      mdxOptions: {
+        remarkPlugins: [remarkGfm],
+        rehypePlugins: [
+          rehypeSlug,
+          [rehypeAutolinkHeadings, { behavior: 'wrap' }],
+        ],
+      },
+      scope: {
+        ...scope,
+        frontmatter,
+      },
+    },
+  })
+  
+  return {
+    content,
+    frontmatter,
+    headings,
+  }
+}
+
+/**
+ * Quick compile for previews (less validation)
+ */
+export async function quickCompileMDX(
+  source: string,
+  components: Record<string, React.ComponentType<unknown>> = {}
+): Promise<{ content: React.ReactElement; frontmatter: Record<string, unknown> }> {
+  const { content: mdxContent, data: frontmatter } = extractFrontmatter(source)
+  
+  const { content } = await compileMDX({
+    source: mdxContent,
+    components,
+    options: {
+      parseFrontmatter: false,
+      mdxOptions: {
+        remarkPlugins: [remarkGfm],
+        rehypePlugins: [rehypeSlug],
+      },
+    },
+  })
+  
+  return { content, frontmatter }
+}
+
+/**
+ * Validate MDX content without compiling (for linting)
+ */
+export function validateMDXContent(source: string): {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+} {
+  const errors: string[] = []
+  const warnings: string[] = []
+  
+  try {
+    const { data } = extractFrontmatter(source)
+    
+    // Check frontmatter
+    const frontmatterResult = safeParseFrontmatter(data)
+    if (!frontmatterResult) {
+      errors.push('Invalid frontmatter format')
+    }
+    
+    // Check for common issues
+    if (!data.title) {
+      warnings.push('Missing title in frontmatter')
+    }
+    
+    if (!data.description) {
+      warnings.push('Missing description in frontmatter (recommended for SEO)')
+    }
+    
+  } catch (error) {
+    errors.push(`Parse error: ${error instanceof Error ? error.message : 'Unknown error'}`)
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}

package/renderer/lib/docs/mdx/frontmatter.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod'
+
+/**
+ * Frontmatter Schema for MDX Documentation Pages
+ * 
+ * Defines the structure and validation for page metadata
+ * Compatible with Mintlify-style frontmatter
+ */
+
+export const frontmatterSchema = z.object({
+  // Core metadata
+  title: z.string(),
+  description: z.string().optional(),
+  
+  // Navigation
+  sidebarTitle: z.string().optional(),
+  icon: z.string().optional(),
+  
+  // Page behavior
+  mode: z.enum(['default', 'wide', 'custom']).optional(),
+  
+  // OpenAPI integration
+  openapi: z.string().optional(),
+  api: z.string().optional(),
+  
+  // SEO
+  'og:title': z.string().optional(),
+  'og:description': z.string().optional(),
+  'og:image': z.string().optional(),
+  'twitter:title': z.string().optional(),
+  'twitter:description': z.string().optional(),
+  
+  // Visibility
+  hidden: z.boolean().optional(),
+  noindex: z.boolean().optional(),
+  
+  // Version/Status
+  version: z.string().optional(),
+  deprecated: z.boolean().optional(),
+})
+
+export type Frontmatter = z.infer<typeof frontmatterSchema>
+
+/**
+ * Parse and validate frontmatter data
+ * Returns the validated data or throws an error with details
+ */
+export function parseFrontmatter(data: unknown): Frontmatter {
+  const result = frontmatterSchema.safeParse(data)
+  
+  if (!result.success) {
+    const issues = result.error.issues || []
+    const errors = issues.map((e) => 
+      `${e.path.map(String).join('.')}: ${e.message}`
+    ).join('\n')
+    throw new Error(`Invalid frontmatter:\n${errors}`)
+  }
+  
+  return result.data
+}
+
+/**
+ * Safe parse that returns null on failure instead of throwing
+ */
+export function safeParseFrontmatter(data: unknown): Frontmatter | null {
+  const result = frontmatterSchema.safeParse(data)
+  return result.success ? result.data : null
+}
+
+/**
+ * Get default frontmatter values
+ */
+export function getDefaultFrontmatter(): Partial<Frontmatter> {
+  return {
+    mode: 'default',
+    hidden: false,
+    noindex: false,
+    deprecated: false,
+  }
+}

package/renderer/lib/docs/mdx/index.ts

@@ -0,0 +1,26 @@
+/**
+ * MDX Library Exports
+ * 
+ * Core utilities for MDX compilation and processing
+ */
+
+// Compiler utilities
+export {
+  compileMDXContent,
+  quickCompileMDX,
+  validateMDXContent,
+  extractFrontmatter,
+  extractHeadings,
+  type MDXCompileResult,
+  type TableOfContentsItem,
+  type CompileMDXOptions,
+} from './compiler'
+
+// Frontmatter
+export {
+  frontmatterSchema,
+  parseFrontmatter,
+  safeParseFrontmatter,
+  getDefaultFrontmatter,
+  type Frontmatter,
+} from './frontmatter'

package/renderer/lib/docs/navigation/generator.ts

@@ -0,0 +1,348 @@
+import { relative, basename, extname } from 'path'
+import { 
+  type DocsConfig, 
+  type NavigationTab, 
+  type NavigationGroup,
+  resolvePagePath,
+  loadPageContent,
+} from '../config'
+import { extractFrontmatter, safeParseFrontmatter } from '../mdx'
+import type { 
+  Navigation, 
+  NavTab, 
+  NavGroup, 
+  NavItem, 
+  PageNavContext,
+  BreadcrumbItem,
+  PageMeta,
+} from './types'
+
+/**
+ * Navigation Generator
+ * 
+ * Builds navigation structure from docs.json configuration
+ */
+
+/**
+ * Generate navigation from configuration
+ */
+export function generateNavigation(
+  config: DocsConfig,
+  docsDir: string
+): Navigation {
+  const nav = config.navigation
+  const navigation: Navigation = {}
+  
+  // Handle tabbed navigation
+  if (nav.tabs && nav.tabs.length > 0) {
+    navigation.tabs = nav.tabs.map(tab => buildNavTab(tab, docsDir))
+  }
+  
+  // Handle single-page navigation (no tabs)
+  if (nav.groups && nav.groups.length > 0) {
+    navigation.groups = nav.groups.map(group => buildNavGroup(group, docsDir))
+  }
+  
+  // Add global anchors
+  if (nav.global?.anchors) {
+    navigation.anchors = nav.global.anchors.map(anchor => ({
+      title: anchor.anchor,
+      href: anchor.href,
+      icon: anchor.icon,
+      external: anchor.href.startsWith('http'),
+    }))
+  }
+  
+  return navigation
+}
+
+/**
+ * Build a navigation tab
+ */
+function buildNavTab(
+  tab: NavigationTab,
+  docsDir: string
+): NavTab {
+  const slug = tab.tab.toLowerCase().replace(/\s+/g, '-')
+  
+  // Only docs tabs have groups
+  if ('groups' in tab && tab.groups) {
+    const groups = tab.groups.map(group => buildNavGroup(group, docsDir))
+    return {
+      title: tab.tab,
+      slug,
+      groups,
+    }
+  }
+  
+  // For openapi/changelog tabs, return empty groups
+  return {
+    title: tab.tab,
+    slug,
+    groups: [],
+  }
+}
+
+/**
+ * Build a navigation group
+ */
+function buildNavGroup(
+  group: NavigationGroup,
+  docsDir: string
+): NavGroup {
+  const items = group.pages
+    .map(page => buildNavItemOrGroup(page, docsDir))
+    .filter((item): item is NavItem | NavGroup => item !== null)
+  
+  return {
+    title: group.group,
+    icon: group.icon,
+    items,
+    collapsible: true,
+    defaultCollapsed: false,
+  }
+}
+
+/**
+ * Build a navigation item or nested group from a page reference
+ */
+function buildNavItemOrGroup(
+  pageRef: string | { group: string; pages: (string | object)[] },
+  docsDir: string
+): NavItem | NavGroup | null {
+  // Handle nested groups
+  if (typeof pageRef === 'object' && 'group' in pageRef) {
+    const nestedItems = pageRef.pages
+      .map(p => buildNavItemOrGroup(p as string | { group: string; pages: (string | object)[] }, docsDir))
+      .filter((item): item is NavItem | NavGroup => item !== null)
+    
+    return {
+      title: pageRef.group,
+      items: nestedItems,
+      collapsible: true,
+      defaultCollapsed: false,
+    }
+  }
+  
+  return buildNavItem(pageRef, docsDir)
+}
+
+/**
+ * Build a navigation item from a page reference
+ */
+function buildNavItem(
+  pageRef: string,
+  docsDir: string
+): NavItem | null {
+  // Check if it's an external link
+  if (pageRef.startsWith('http://') || pageRef.startsWith('https://')) {
+    return {
+      title: pageRef,
+      href: pageRef,
+      external: true,
+    }
+  }
+  
+  // Resolve the page file
+  const filePath = resolvePagePath(docsDir, pageRef)
+  
+  if (!filePath) {
+    console.warn(`Page not found: ${pageRef}`)
+    return {
+      title: pageRef,
+      href: `/${pageRef}`,
+    }
+  }
+  
+  // Load and parse frontmatter
+  try {
+    const content = loadPageContent(filePath)
+    const { data } = extractFrontmatter(content)
+    const frontmatter = safeParseFrontmatter(data)
+    
+    // Build URL path
+    const urlPath = pageRef === 'index' ? '/' : `/${pageRef}`
+    
+    return {
+      title: frontmatter?.sidebarTitle || frontmatter?.title || pageRef,
+      href: urlPath,
+      icon: frontmatter?.icon,
+      deprecated: frontmatter?.deprecated,
+    }
+  } catch (error) {
+    console.warn(`Failed to load page metadata: ${pageRef}`, error)
+    return {
+      title: pageRef,
+      href: `/${pageRef}`,
+    }
+  }
+}
+
+/**
+ * Helper to check if an item is a NavItem (has href)
+ */
+function isNavItem(item: NavItem | NavGroup): item is NavItem {
+  return 'href' in item && typeof item.href === 'string'
+}
+
+/**
+ * Recursively collect all NavItems from items array (handles nested groups)
+ */
+function collectNavItems(items: (NavItem | NavGroup)[]): NavItem[] {
+  const result: NavItem[] = []
+  for (const item of items) {
+    if (isNavItem(item)) {
+      result.push(item)
+    } else if ('items' in item && Array.isArray(item.items)) {
+      result.push(...collectNavItems(item.items))
+    }
+  }
+  return result
+}
+
+/**
+ * Find navigation context for a specific page
+ */
+export function findPageNavContext(
+  navigation: Navigation,
+  currentPath: string
+): PageNavContext {
+  const breadcrumbs: BreadcrumbItem[] = []
+  let prev: NavItem | undefined
+  let next: NavItem | undefined
+  let currentTab: NavTab | undefined
+  let currentGroup: NavGroup | undefined
+  let currentItem: NavItem | undefined
+  
+  // Normalize path
+  const normalizedPath = currentPath.startsWith('/') ? currentPath : `/${currentPath}`
+  
+  // Flatten all items for prev/next calculation
+  const allItems: NavItem[] = []
+  
+  // Search in tabs
+  if (navigation.tabs) {
+    for (const tab of navigation.tabs) {
+      for (const group of tab.groups) {
+        const groupItems = collectNavItems(group.items)
+        allItems.push(...groupItems)
+        
+        for (const item of groupItems) {
+          if (item.href === normalizedPath) {
+            currentTab = tab
+            currentGroup = group
+            currentItem = item
+            
+            // Build breadcrumbs
+            breadcrumbs.push({ title: tab.title, href: `/${tab.slug}` })
+            breadcrumbs.push({ title: group.title, href: '#' })
+            breadcrumbs.push({ title: item.title, href: item.href })
+          }
+        }
+      }
+    }
+  }
+  
+  // Search in groups (non-tabbed)
+  if (navigation.groups) {
+    for (const group of navigation.groups) {
+      const groupItems = collectNavItems(group.items)
+      allItems.push(...groupItems)
+      
+      for (const item of groupItems) {
+        if (item.href === normalizedPath) {
+          currentGroup = group
+          currentItem = item
+          
+          // Build breadcrumbs
+          breadcrumbs.push({ title: group.title, href: '#' })
+          breadcrumbs.push({ title: item.title, href: item.href })
+        }
+      }
+    }
+  }
+  
+  // Find prev/next
+  const currentIndex = allItems.findIndex(item => item.href === normalizedPath)
+  if (currentIndex > 0) {
+    prev = allItems[currentIndex - 1]
+  }
+  if (currentIndex >= 0 && currentIndex < allItems.length - 1) {
+    next = allItems[currentIndex + 1]
+  }
+  
+  return {
+    breadcrumbs,
+    prev,
+    next,
+    currentTab,
+    currentGroup,
+    currentItem,
+  }
+}
+
+/**
+ * Get all page paths from navigation
+ */
+export function getAllPagePaths(navigation: Navigation): string[] {
+  const paths: string[] = []
+  
+  if (navigation.tabs) {
+    for (const tab of navigation.tabs) {
+      for (const group of tab.groups) {
+        const items = collectNavItems(group.items)
+        for (const item of items) {
+          if (!item.external) {
+            paths.push(item.href)
+          }
+        }
+      }
+    }
+  }
+  
+  if (navigation.groups) {
+    for (const group of navigation.groups) {
+      const items = collectNavItems(group.items)
+      for (const item of items) {
+        if (!item.external) {
+          paths.push(item.href)
+        }
+      }
+    }
+  }
+  
+  return paths
+}
+
+/**
+ * Load page metadata from file
+ */
+export function loadPageMeta(
+  filePath: string,
+  docsDir: string
+): PageMeta | null {
+  try {
+    const content = loadPageContent(filePath)
+    const { data } = extractFrontmatter(content)
+    const frontmatter = safeParseFrontmatter(data)
+    
+    // Calculate URL path from file path
+    const relativePath = relative(docsDir, filePath)
+    const urlPath = '/' + relativePath
+      .replace(/\.(mdx?|md)$/, '')
+      .replace(/\/index$/, '')
+      .replace(/^index$/, '')
+    
+    return {
+      filePath: relativePath,
+      urlPath: urlPath || '/',
+      title: frontmatter?.title || basename(filePath, extname(filePath)),
+      description: frontmatter?.description,
+      sidebarTitle: frontmatter?.sidebarTitle,
+      icon: frontmatter?.icon,
+      hidden: frontmatter?.hidden,
+    }
+  } catch {
+    return null
+  }
+}

package/renderer/lib/docs/navigation/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Navigation Module Exports
+ */
+
+export * from './types'
+
+export {
+  generateNavigation,
+  findPageNavContext,
+  getAllPagePaths,
+  loadPageMeta,
+} from './generator'