@brainfish-ai/devdoc 0.1.21

package/renderer/lib/api-docs/factories.ts

@@ -0,0 +1,151 @@
+/**
+ * Factory Functions for Brainfish API Documentation
+ * 
+ * Creates instances of BrainfishCollection and BrainfishRESTRequest
+ * with proper defaults and unique IDs.
+ */
+
+import type {
+  BrainfishCollection,
+  BrainfishRESTRequest,
+} from './types'
+
+/**
+ * Generates a unique ID for collections and requests
+ * If a seed is provided, generates a deterministic hash-based ID
+ */
+function generateUniqueId(prefix: string, seed?: string): string {
+  if (seed) {
+    // Generate deterministic ID from seed using simple hash
+    let hash = 0
+    for (let i = 0; i < seed.length; i++) {
+      const char = seed.charCodeAt(i)
+      hash = ((hash << 5) - hash) + char
+      hash = hash & hash // Convert to 32bit integer
+    }
+    // Convert to positive number and base36
+    const hashStr = Math.abs(hash).toString(36)
+    return `${prefix}_${hashStr}`
+  }
+  return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+}
+
+/**
+ * Creates a BrainfishRESTRequest with defaults
+ * If method and endpoint are provided, generates a deterministic ID
+ */
+export function makeBrainfishRESTRequest(
+  request: Omit<BrainfishRESTRequest, 'id'>
+): BrainfishRESTRequest {
+  // Generate deterministic ID from method + endpoint
+  const idSeed = request.method && request.endpoint 
+    ? `${request.method}:${request.endpoint}` 
+    : undefined
+  
+  return {
+    id: generateUniqueId('req', idSeed),
+    name: request.name || 'Untitled Request',
+    description: request.description ?? null,
+    method: request.method || 'GET',
+    endpoint: request.endpoint || '',
+    params: request.params || [],
+    headers: request.headers || [],
+    auth: request.auth || { authType: 'none', authActive: true },
+    body: request.body || { contentType: null, body: null },
+    requestVariables: request.requestVariables || [],
+    responses: request.responses || {},
+    tags: request.tags || [],
+  }
+}
+
+/**
+ * Creates a BrainfishCollection with defaults
+ * If name is provided, generates a deterministic ID
+ */
+export function makeBrainfishCollection(
+  collection: Omit<BrainfishCollection, 'id'>
+): BrainfishCollection {
+  // Generate deterministic ID from collection name
+  const idSeed = collection.name ? `collection:${collection.name}` : undefined
+  
+  return {
+    id: generateUniqueId('coll', idSeed),
+    name: collection.name || 'Untitled Collection',
+    description: collection.description ?? null,
+    folders: collection.folders || [],
+    requests: collection.requests || [],
+    variables: collection.variables || [],
+    auth: collection.auth || { authType: 'inherit', authActive: true },
+    headers: collection.headers || [],
+  }
+}
+
+/**
+ * Creates a default BrainfishRESTRequest
+ */
+export function getDefaultBrainfishRESTRequest(): BrainfishRESTRequest {
+  return makeBrainfishRESTRequest({
+    name: 'Untitled Request',
+    description: null,
+    method: 'GET',
+    endpoint: '',
+    params: [],
+    headers: [],
+    auth: {
+      authType: 'none',
+      authActive: true,
+    },
+    body: {
+      contentType: null,
+      body: null,
+    },
+    requestVariables: [],
+    responses: {},
+    tags: [],
+  })
+}
+
+/**
+ * Creates a default BrainfishCollection
+ */
+export function getDefaultBrainfishCollection(): BrainfishCollection {
+  return makeBrainfishCollection({
+    name: 'Untitled Collection',
+    description: null,
+    folders: [],
+    requests: [],
+    variables: [],
+    auth: {
+      authType: 'inherit',
+      authActive: true,
+    },
+    headers: [],
+  })
+}
+
+/**
+ * Creates a BrainfishRESTResponseOriginalRequest
+ */
+export function makeBrainfishRESTResponseOriginalRequest(
+  request: {
+    name: string
+    method: BrainfishRESTRequest['method']
+    endpoint: string
+    params: BrainfishRESTRequest['params']
+    headers: BrainfishRESTRequest['headers']
+    body: BrainfishRESTRequest['body']
+    auth: BrainfishRESTRequest['auth']
+    requestVariables: BrainfishRESTRequest['requestVariables']
+  }
+) {
+  return {
+    name: request.name,
+    method: request.method,
+    endpoint: request.endpoint,
+    params: request.params,
+    headers: request.headers,
+    body: request.body,
+    auth: request.auth,
+    requestVariables: request.requestVariables,
+  }
+}

package/renderer/lib/api-docs/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Brainfish API Documentation - Main Export
+ * 
+ * This module exports all types, factories, and utilities for the API documentation system.
+ */
+
+// Types
+export * from './types'
+
+// Factories
+export * from './factories'
+
+// Utils
+export * from './utils'
+
+// Parsers
+export * from './parsers/openapi'

package/renderer/lib/api-docs/mobile-context.tsx

@@ -0,0 +1,112 @@
+'use client'
+
+import { createContext, useContext, useState, useCallback, useEffect, type ReactNode } from 'react'
+
+interface MobileContextValue {
+  // Sidebar visibility
+  isLeftSidebarOpen: boolean
+  isRightSidebarOpen: boolean
+  // Toggle functions
+  toggleLeftSidebar: () => void
+  toggleRightSidebar: () => void
+  openLeftSidebar: () => void
+  closeLeftSidebar: () => void
+  openRightSidebar: () => void
+  closeRightSidebar: () => void
+  // Close all sidebars (useful when navigating)
+  closeAllSidebars: () => void
+  // Mobile detection
+  isMobile: boolean
+}
+
+const MobileContext = createContext<MobileContextValue | null>(null)
+
+export function MobileProvider({ children }: { children: ReactNode }) {
+  const [isLeftSidebarOpen, setIsLeftSidebarOpen] = useState(false)
+  const [isRightSidebarOpen, setIsRightSidebarOpen] = useState(false)
+  const [isMobile, setIsMobile] = useState(false)
+
+  // Detect mobile on mount and window resize
+  useEffect(() => {
+    const checkMobile = () => {
+      setIsMobile(window.innerWidth < 1024) // lg breakpoint
+    }
+    
+    // Initial check
+    checkMobile()
+    
+    // Listen for resize
+    window.addEventListener('resize', checkMobile)
+    return () => window.removeEventListener('resize', checkMobile)
+  }, [])
+
+  // Close sidebars when switching to desktop
+  useEffect(() => {
+    if (!isMobile) {
+      setIsLeftSidebarOpen(false)
+      setIsRightSidebarOpen(false)
+    }
+  }, [isMobile])
+
+  const toggleLeftSidebar = useCallback(() => {
+    setIsLeftSidebarOpen(prev => !prev)
+    // Close right sidebar when opening left
+    setIsRightSidebarOpen(false)
+  }, [])
+
+  const toggleRightSidebar = useCallback(() => {
+    setIsRightSidebarOpen(prev => !prev)
+    // Close left sidebar when opening right
+    setIsLeftSidebarOpen(false)
+  }, [])
+
+  const openLeftSidebar = useCallback(() => {
+    setIsLeftSidebarOpen(true)
+    setIsRightSidebarOpen(false)
+  }, [])
+
+  const closeLeftSidebar = useCallback(() => {
+    setIsLeftSidebarOpen(false)
+  }, [])
+
+  const openRightSidebar = useCallback(() => {
+    setIsRightSidebarOpen(true)
+    setIsLeftSidebarOpen(false)
+  }, [])
+
+  const closeRightSidebar = useCallback(() => {
+    setIsRightSidebarOpen(false)
+  }, [])
+
+  const closeAllSidebars = useCallback(() => {
+    setIsLeftSidebarOpen(false)
+    setIsRightSidebarOpen(false)
+  }, [])
+
+  return (
+    <MobileContext.Provider
+      value={{
+        isLeftSidebarOpen,
+        isRightSidebarOpen,
+        toggleLeftSidebar,
+        toggleRightSidebar,
+        openLeftSidebar,
+        closeLeftSidebar,
+        openRightSidebar,
+        closeRightSidebar,
+        closeAllSidebars,
+        isMobile,
+      }}
+    >
+      {children}
+    </MobileContext.Provider>
+  )
+}
+
+export function useMobile() {
+  const context = useContext(MobileContext)
+  if (!context) {
+    throw new Error('useMobile must be used within a MobileProvider')
+  }
+  return context
+}

package/renderer/lib/api-docs/navigation-context.tsx

@@ -0,0 +1,88 @@
+'use client'
+
+import { createContext, useContext, useCallback, type ReactNode } from 'react'
+import type { BrainfishCollection, BrainfishRESTRequest } from './types'
+
+interface NavigationContextValue {
+  /** Navigate to an endpoint by operationId or ID */
+  navigateToEndpoint: (operationIdOrId: string) => void
+  /** Current collection */
+  collection: BrainfishCollection | null
+}
+
+const NavigationContext = createContext<NavigationContextValue | null>(null)
+
+interface NavigationProviderProps {
+  children: ReactNode
+  collection: BrainfishCollection | null
+  onSelectRequest: (request: BrainfishRESTRequest) => void
+}
+
+/**
+ * Helper to find request by operationId (name) or ID in collection
+ */
+function findRequestByOperationIdOrId(
+  collection: BrainfishCollection,
+  operationIdOrId: string
+): BrainfishRESTRequest | null {
+  // Normalize the search term (handle both snake_case and the formatted name)
+  const normalizedSearch = operationIdOrId.toLowerCase().replace(/[\s-]/g, '_')
+  
+  // Check direct requests
+  for (const request of collection.requests) {
+    // Check by ID
+    if (request.id === operationIdOrId) return request
+    // Check by name (operationId) - exact match
+    if (request.name.toLowerCase().replace(/[\s-]/g, '_') === normalizedSearch) return request
+    // Check by name - partial match (for formatted names like "Post Carts" -> "post_carts")
+    const requestNameNormalized = request.name.toLowerCase().replace(/[\s-]/g, '_')
+    if (requestNameNormalized === normalizedSearch) return request
+  }
+  
+  // Check folders recursively
+  for (const folder of collection.folders) {
+    const request = findRequestByOperationIdOrId(folder, operationIdOrId)
+    if (request) return request
+  }
+  
+  return null
+}
+
+export function NavigationProvider({ 
+  children, 
+  collection, 
+  onSelectRequest 
+}: NavigationProviderProps) {
+  const navigateToEndpoint = useCallback((operationIdOrId: string) => {
+    if (!collection) {
+      console.warn('[Navigation] No collection available')
+      return
+    }
+    
+    const request = findRequestByOperationIdOrId(collection, operationIdOrId)
+    if (request) {
+      console.log('[Navigation] Navigating to endpoint:', request.name)
+      onSelectRequest(request)
+    } else {
+      console.warn('[Navigation] Endpoint not found:', operationIdOrId)
+    }
+  }, [collection, onSelectRequest])
+  
+  return (
+    <NavigationContext.Provider value={{ navigateToEndpoint, collection }}>
+      {children}
+    </NavigationContext.Provider>
+  )
+}
+
+export function useNavigation() {
+  const context = useContext(NavigationContext)
+  if (!context) {
+    // Return a no-op function if not in provider (for backwards compatibility)
+    return {
+      navigateToEndpoint: () => {},
+      collection: null
+    }
+  }
+  return context
+}

package/renderer/lib/api-docs/parsers/graphql/README.md

@@ -0,0 +1,129 @@
+# GraphQL Parser
+
+This directory contains the GraphQL schema parsing logic for Brainfish API Docs.
+
+## Structure
+
+- `types.ts` - TypeScript types for GraphQL schema representation
+- `parser.ts` - GraphQL SDL parsing using graphql-js
+- `transformer.ts` - Convert GraphQL schema to BrainfishCollection
+- `index.ts` - Main entry point and exports
+
+## Dependencies Required
+
+```bash
+npm install graphql
+```
+
+## Usage
+
+### Parse GraphQL Schema
+
+```typescript
+import { importGraphQLSchema } from '@/lib/api-docs/parsers/graphql'
+
+// Parse SDL string
+const collection = await importGraphQLSchema(sdlString, {
+  name: 'My GraphQL API',
+  endpoint: 'https://api.example.com/graphql',
+})
+```
+
+### Get Full Schema Information
+
+```typescript
+import { importGraphQLSchemaFull } from '@/lib/api-docs/parsers/graphql'
+
+const graphqlCollection = await importGraphQLSchemaFull(sdlString, {
+  name: 'My GraphQL API',
+  endpoint: 'https://api.example.com/graphql',
+})
+
+// Access queries, mutations, subscriptions, and types
+console.log(graphqlCollection.queries)
+console.log(graphqlCollection.mutations)
+console.log(graphqlCollection.types)
+```
+
+### Parse Schema Only
+
+```typescript
+import { parseGraphQL } from '@/lib/api-docs/parsers/graphql'
+
+const schema = await parseGraphQL(sdlString)
+
+// Access schema information
+console.log(schema.info)
+console.log(schema.types)
+console.log(schema.queries)
+```
+
+## Configuration in docs.json
+
+Add a GraphQL tab to your navigation:
+
+```json
+{
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "GraphQL API",
+        "type": "graphql",
+        "path": "/graphql",
+        "schema": "api-reference/schema.graphql",
+        "endpoint": "https://api.example.com/graphql"
+      }
+    ]
+  }
+}
+```
+
+### Multiple Schemas
+
+```json
+{
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "GraphQL API",
+        "type": "graphql",
+        "path": "/graphql",
+        "schemas": [
+          {
+            "name": "Public API",
+            "schema": "api-reference/public.graphql",
+            "endpoint": "https://api.example.com/graphql",
+            "default": true
+          },
+          {
+            "name": "Admin API",
+            "schema": "api-reference/admin.graphql",
+            "endpoint": "https://admin.example.com/graphql"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Features
+
+- **SDL Parsing**: Parse GraphQL Schema Definition Language files
+- **Introspection**: Support for introspection query results (planned)
+- **Type Explorer**: View all types, inputs, enums, interfaces, unions
+- **Operation Playground**: Test queries, mutations, and subscriptions
+- **Variable Support**: Auto-generate example variables from schema
+- **Documentation**: Extract descriptions from schema for docs
+
+## Architecture
+
+The GraphQL parser follows the same pattern as the OpenAPI parser:
+
+1. **Parse**: Read SDL or introspection result
+2. **Validate**: Ensure schema is valid GraphQL
+3. **Transform**: Convert to internal types
+4. **Export**: Generate BrainfishCollection for UI
+
+This allows GraphQL APIs to use the same documentation UI as REST APIs,
+with GraphQL-specific enhancements for the schema explorer and playground.

package/renderer/lib/api-docs/parsers/graphql/index.ts

@@ -0,0 +1,91 @@
+/**
+ * GraphQL Parser Module
+ * 
+ * Main entry point for GraphQL schema parsing and transformation.
+ */
+
+export * from './types'
+export * from './parser'
+export * from './transformer'
+
+import { parseGraphQLSchema, validateGraphQLSchema } from './parser'
+import { convertGraphQLToBrainfishCollection, convertGraphQLToCollection } from './transformer'
+import type { BrainfishCollection } from '../../types'
+import type { BrainfishGraphQLCollection, GraphQLSchema } from './types'
+
+export const GRAPHQL_INVALID_SCHEMA = 'graphql/invalid_schema' as const
+
+/**
+ * Import a GraphQL schema from SDL string or file content
+ * Returns a BrainfishCollection for integration with existing UI
+ */
+export async function importGraphQLSchema(
+  input: string,
+  options: {
+    name?: string
+    endpoint?: string
+    description?: string
+  } = {}
+): Promise<BrainfishCollection> {
+  const {
+    name = 'GraphQL API',
+    endpoint = '/graphql',
+    description,
+  } = options
+
+  // Validate the schema
+  const validation = validateGraphQLSchema(input)
+  if (!validation.valid) {
+    throw new Error(`${GRAPHQL_INVALID_SCHEMA}: ${validation.error}`)
+  }
+
+  // Parse the schema
+  const schema = parseGraphQLSchema(input)
+
+  // Convert to BrainfishCollection
+  return convertGraphQLToBrainfishCollection(schema, name, endpoint, description)
+}
+
+/**
+ * Import a GraphQL schema and return the full GraphQL collection
+ * with schema information preserved
+ */
+export async function importGraphQLSchemaFull(
+  input: string,
+  options: {
+    name?: string
+    endpoint?: string
+    description?: string
+  } = {}
+): Promise<BrainfishGraphQLCollection> {
+  const {
+    name = 'GraphQL API',
+    endpoint = '/graphql',
+    description,
+  } = options
+
+  // Validate the schema
+  const validation = validateGraphQLSchema(input)
+  if (!validation.valid) {
+    throw new Error(`${GRAPHQL_INVALID_SCHEMA}: ${validation.error}`)
+  }
+
+  // Parse the schema
+  const schema = parseGraphQLSchema(input)
+
+  // Convert to full GraphQL collection
+  return convertGraphQLToCollection(schema, name, endpoint, description)
+}
+
+/**
+ * Parse GraphQL schema without converting to collection
+ * Useful for schema exploration and type information
+ */
+export async function parseGraphQL(input: string): Promise<GraphQLSchema> {
+  const validation = validateGraphQLSchema(input)
+  if (!validation.valid) {
+    throw new Error(`${GRAPHQL_INVALID_SCHEMA}: ${validation.error}`)
+  }
+
+  return parseGraphQLSchema(input)
+}