@brainfish-ai/devdoc 0.1.42 → 0.1.44

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

@@ -0,0 +1,131 @@
+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 } from './frontmatter';
+import { remarkMermaid } from './remark-mermaid';
+/**
+ * Extract frontmatter from raw MDX content
+ */ export function extractFrontmatter(source) {
+    const { content, data } = matter(source);
+    return {
+        content,
+        data
+    };
+}
+/**
+ * Extract headings from MDX content for table of contents
+ */ export function extractHeadings(content) {
+    const headingRegex = /^(#{1,6})\s+(.+)$/gm;
+    const headings = [];
+    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(source, options = {}) {
+    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) : rawFrontmatter;
+    // Extract headings for ToC
+    const headings = extractHeadings(mdxContent);
+    // Compile MDX
+    const { content } = await compileMDX({
+        source: mdxContent,
+        components,
+        options: {
+            parseFrontmatter: false,
+            mdxOptions: {
+                remarkPlugins: [
+                    remarkGfm,
+                    remarkMermaid
+                ],
+                rehypePlugins: [
+                    rehypeSlug,
+                    [
+                        rehypeAutolinkHeadings,
+                        {
+                            behavior: 'wrap'
+                        }
+                    ]
+                ]
+            },
+            scope: {
+                ...scope,
+                frontmatter
+            }
+        }
+    });
+    return {
+        content,
+        frontmatter,
+        headings
+    };
+}
+/**
+ * Quick compile for previews (less validation)
+ */ export async function quickCompileMDX(source, components = {}) {
+    const { content: mdxContent, data: frontmatter } = extractFrontmatter(source);
+    const { content } = await compileMDX({
+        source: mdxContent,
+        components,
+        options: {
+            parseFrontmatter: false,
+            mdxOptions: {
+                remarkPlugins: [
+                    remarkGfm,
+                    remarkMermaid
+                ],
+                rehypePlugins: [
+                    rehypeSlug
+                ]
+            }
+        }
+    });
+    return {
+        content,
+        frontmatter
+    };
+}
+/**
+ * Validate MDX content without compiling (for linting)
+ */ export function validateMDXContent(source) {
+    const errors = [];
+    const warnings = [];
+    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.js

@@ -0,0 +1,73 @@
+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
+    // - 'default': Standard documentation page with max-width container
+    // - 'wide': Wide container for content that needs more space
+    // - 'custom': Full-width custom layout (no container, no header) - for landing pages
+    mode: z.enum([
+        'default',
+        'wide',
+        'custom'
+    ]).optional(),
+    // Custom page options (only used when mode: 'custom')
+    // Hides the default page header (title & description)
+    hideHeader: z.boolean().optional(),
+    // Full-width layout without container constraints
+    fullWidth: z.boolean().optional(),
+    // Custom background color or gradient
+    background: z.string().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()
+});
+/**
+ * Parse and validate frontmatter data
+ * Returns the validated data or throws an error with details
+ */ export function parseFrontmatter(data) {
+    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) {
+    const result = frontmatterSchema.safeParse(data);
+    return result.success ? result.data : null;
+}
+/**
+ * Get default frontmatter values
+ */ export function getDefaultFrontmatter() {
+    return {
+        mode: 'default',
+        hidden: false,
+        noindex: false,
+        deprecated: false
+    };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * MDX Library Exports
+ * 
+ * Core utilities for MDX compilation and processing
+ */ // Compiler utilities
+export { compileMDXContent, quickCompileMDX, validateMDXContent, extractFrontmatter, extractHeadings } from './compiler';
+// Frontmatter
+export { frontmatterSchema, parseFrontmatter, safeParseFrontmatter, getDefaultFrontmatter } from './frontmatter';
+// Remark plugins
+export { remarkMermaid } from './remark-mermaid';

package/renderer/lib/docs/mdx/remark-mermaid.js

@@ -0,0 +1,63 @@
+import { visit } from 'unist-util-visit';
+/**
+ * Remark plugin to transform mermaid code blocks into Mermaid components
+ * 
+ * Transforms:
+ * ```mermaid
+ * flowchart LR
+ *     A --> B
+ * ```
+ * 
+ * Into:
+ * <Mermaid>
+ * {`flowchart LR
+ *     A --> B`}
+ * </Mermaid>
+ */ export function remarkMermaid() {
+    return (tree)=>{
+        visit(tree, 'code', (node, index, parent)=>{
+            if (node.lang !== 'mermaid' || !parent || index === undefined) {
+                return;
+            }
+            // Replace the code block with MDX JSX element
+            const mermaidNode = {
+                type: 'mdxJsxFlowElement',
+                name: 'Mermaid',
+                attributes: [],
+                children: [
+                    {
+                        type: 'mdxFlowExpression',
+                        value: '`' + node.value + '`',
+                        data: {
+                            estree: {
+                                type: 'Program',
+                                body: [
+                                    {
+                                        type: 'ExpressionStatement',
+                                        expression: {
+                                            type: 'TemplateLiteral',
+                                            expressions: [],
+                                            quasis: [
+                                                {
+                                                    type: 'TemplateElement',
+                                                    value: {
+                                                        raw: node.value,
+                                                        cooked: node.value
+                                                    },
+                                                    tail: true
+                                                }
+                                            ]
+                                        }
+                                    }
+                                ],
+                                sourceType: 'module'
+                            }
+                        }
+                    }
+                ]
+            };
+            // Replace the code node with the Mermaid component
+            parent.children.splice(index, 1, mermaidNode);
+        });
+    };
+}

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

@@ -0,0 +1,269 @@
+import { relative, basename, extname } from 'path';
+import { resolvePagePath, loadPageContent } from '../config';
+import { extractFrontmatter, safeParseFrontmatter } from '../mdx';
+/**
+ * Navigation Generator
+ * 
+ * Builds navigation structure from docs.json configuration
+ */ /**
+ * Generate navigation from configuration
+ */ export function generateNavigation(config, docsDir) {
+    const nav = config.navigation;
+    const 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, docsDir) {
+    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, docsDir) {
+    const items = group.pages.map((page)=>buildNavItemOrGroup(page, docsDir)).filter((item)=>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, docsDir) {
+    // Handle nested groups
+    if (typeof pageRef === 'object' && 'group' in pageRef) {
+        const nestedItems = pageRef.pages.map((p)=>buildNavItemOrGroup(p, docsDir)).filter((item)=>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, docsDir) {
+    // 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) {
+    return 'href' in item && typeof item.href === 'string';
+}
+/**
+ * Recursively collect all NavItems from items array (handles nested groups)
+ */ function collectNavItems(items) {
+    const result = [];
+    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, currentPath) {
+    const breadcrumbs = [];
+    let prev;
+    let next;
+    let currentTab;
+    let currentGroup;
+    let currentItem;
+    // Normalize path
+    const normalizedPath = currentPath.startsWith('/') ? currentPath : `/${currentPath}`;
+    // Flatten all items for prev/next calculation
+    const allItems = [];
+    // 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) {
+    const paths = [];
+    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, docsDir) {
+    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.js

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

package/renderer/lib/docs/navigation/types.js

@@ -0,0 +1,11 @@
+/**
+ * Navigation Types
+ * 
+ * Types for the documentation navigation system
+ */ /**
+ * Visibility type for navigation items
+ * - 'public': Always visible (default)
+ * - 'private': Only visible in development mode, hidden in production
+ */ /**
+ * Page metadata for navigation
+ */ export { };

package/renderer/lib/docs-navigation-context.js

@@ -0,0 +1,40 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { createContext, useContext, useCallback } from 'react';
+const DocsNavigationContext = /*#__PURE__*/ createContext(null);
+export function DocsNavigationProvider({ children, onNavigateToPage, onNavigateToEndpoint, onSwitchTab, activeTab }) {
+    const navigateToPage = useCallback((slug)=>{
+        if (onNavigateToPage) {
+            onNavigateToPage(slug);
+        }
+    }, [
+        onNavigateToPage
+    ]);
+    const navigateToEndpoint = useCallback((endpointId)=>{
+        if (onNavigateToEndpoint) {
+            onNavigateToEndpoint(endpointId);
+        }
+    }, [
+        onNavigateToEndpoint
+    ]);
+    const switchToTab = useCallback((tabId)=>{
+        if (onSwitchTab) {
+            onSwitchTab(tabId);
+        }
+    }, [
+        onSwitchTab
+    ]);
+    return /*#__PURE__*/ _jsx(DocsNavigationContext.Provider, {
+        value: {
+            navigateToPage,
+            navigateToEndpoint,
+            switchToTab,
+            isApiDocsView: !!onNavigateToPage,
+            activeTab
+        },
+        children: children
+    });
+}
+export function useDocsNavigation() {
+    return useContext(DocsNavigationContext);
+}