@brainfish-ai/devdoc 0.1.21

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

@@ -0,0 +1,246 @@
+/**
+ * GraphQL Transformer
+ * 
+ * Converts parsed GraphQL schema to BrainfishCollection format
+ * for integration with the existing documentation system.
+ */
+
+import type { BrainfishCollection, BrainfishRESTRequest } from '../../types'
+import { makeBrainfishCollection } from '../../factories'
+import {
+  formatTypeRef,
+  type GraphQLSchema,
+  type GraphQLOperation,
+  type BrainfishGraphQLCollection,
+  type BrainfishGraphQLRequest,
+  type GraphQLTypeDef,
+} from './types'
+import { generateExampleVariables, generateOperationQuery } from './parser'
+
+// ============================================================================
+// GraphQL to REST-like Request Conversion
+// ============================================================================
+
+/**
+ * Convert a GraphQL operation to a REST-like request for the playground
+ * This allows us to reuse the existing API client UI
+ */
+function convertOperationToRESTRequest(
+  operation: GraphQLOperation,
+  endpoint: string
+): BrainfishRESTRequest {
+  // Generate the query string
+  const query = generateOperationQuery(operation)
+  
+  // Generate example variables
+  const variables = generateExampleVariables(operation)
+  
+  // GraphQL always uses POST with JSON body
+  const body = JSON.stringify(
+    {
+      query,
+      variables,
+      operationName: operation.name,
+    },
+    null,
+    2
+  )
+  
+  return {
+    id: operation.id,
+    name: operation.name,
+    description: operation.description || formatOperationDescription(operation),
+    method: 'POST',
+    endpoint,
+    params: [],
+    headers: [
+      {
+        key: 'Content-Type',
+        value: 'application/json',
+        active: true,
+        description: 'GraphQL requests use JSON',
+      },
+    ],
+    auth: {
+      authType: 'inherit',
+      authActive: true,
+    },
+    body: {
+      contentType: 'application/json',
+      body,
+    },
+    requestVariables: operation.args.map(arg => ({
+      key: arg.name,
+      value: JSON.stringify(generateExampleVariables({ ...operation, args: [arg] })[arg.name]),
+      active: true,
+    })),
+    responses: {},
+    tags: [operation.operationType],
+  }
+}
+
+/**
+ * Format a description for an operation based on its signature
+ */
+function formatOperationDescription(operation: GraphQLOperation): string {
+  const args = operation.args
+    .map(arg => `${arg.name}: ${formatTypeRef(arg.type)}`)
+    .join(', ')
+  
+  const returnType = formatTypeRef(operation.returnType)
+  
+  return `${operation.operationType} ${operation.name}(${args}): ${returnType}`
+}
+
+// ============================================================================
+// Main Transformer Functions
+// ============================================================================
+
+/**
+ * Convert GraphQL schema to a BrainfishGraphQLCollection
+ */
+export function convertGraphQLToCollection(
+  schema: GraphQLSchema,
+  name: string,
+  endpoint: string,
+  description?: string
+): BrainfishGraphQLCollection {
+  // Convert operations to our request format
+  const queries: BrainfishGraphQLRequest[] = schema.queries.map(op => ({
+    id: op.id,
+    name: op.name,
+    description: op.description,
+    operationType: 'query',
+    query: generateOperationQuery(op),
+    variables: op.args,
+    returnType: op.returnType,
+    tags: ['Query'],
+    exampleVariables: generateExampleVariables(op),
+  }))
+  
+  const mutations: BrainfishGraphQLRequest[] = schema.mutations.map(op => ({
+    id: op.id,
+    name: op.name,
+    description: op.description,
+    operationType: 'mutation',
+    query: generateOperationQuery(op),
+    variables: op.args,
+    returnType: op.returnType,
+    tags: ['Mutation'],
+    exampleVariables: generateExampleVariables(op),
+  }))
+  
+  const subscriptions: BrainfishGraphQLRequest[] = schema.subscriptions.map(op => ({
+    id: op.id,
+    name: op.name,
+    description: op.description,
+    operationType: 'subscription',
+    query: generateOperationQuery(op),
+    variables: op.args,
+    returnType: op.returnType,
+    tags: ['Subscription'],
+    exampleVariables: generateExampleVariables(op),
+  }))
+  
+  // Extract custom types (exclude built-in scalars)
+  const customTypes: GraphQLTypeDef[] = Object.values(schema.types).filter(
+    type => !['String', 'Int', 'Float', 'Boolean', 'ID'].includes(type.name)
+  )
+  
+  return {
+    id: `graphql-${name.toLowerCase().replace(/\s+/g, '-')}`,
+    name,
+    description: description || schema.info.description,
+    endpoint,
+    schema,
+    queries,
+    mutations,
+    subscriptions,
+    types: customTypes,
+  }
+}
+
+/**
+ * Convert GraphQL schema to BrainfishCollection format
+ * This allows integration with the existing REST-based UI
+ */
+export function convertGraphQLToBrainfishCollection(
+  schema: GraphQLSchema,
+  name: string,
+  endpoint: string,
+  description?: string
+): BrainfishCollection {
+  // Create folders for each operation type
+  const queryFolder = makeBrainfishCollection({
+    name: 'Queries',
+    description: 'GraphQL Query operations',
+    requests: schema.queries.map(op => convertOperationToRESTRequest(op, endpoint)),
+    folders: [],
+    variables: [],
+    auth: { authType: 'none', authActive: false },
+    headers: [],
+  })
+  
+  const mutationFolder = makeBrainfishCollection({
+    name: 'Mutations',
+    description: 'GraphQL Mutation operations',
+    requests: schema.mutations.map(op => convertOperationToRESTRequest(op, endpoint)),
+    folders: [],
+    variables: [],
+    auth: { authType: 'none', authActive: false },
+    headers: [],
+  })
+  
+  const subscriptionFolder = makeBrainfishCollection({
+    name: 'Subscriptions',
+    description: 'GraphQL Subscription operations',
+    requests: schema.subscriptions.map(op => convertOperationToRESTRequest(op, endpoint)),
+    folders: [],
+    variables: [],
+    auth: { authType: 'none', authActive: false },
+    headers: [],
+  })
+  
+  // Only include folders that have operations
+  const folders: BrainfishCollection[] = []
+  if (schema.queries.length > 0) folders.push(queryFolder)
+  if (schema.mutations.length > 0) folders.push(mutationFolder)
+  if (schema.subscriptions.length > 0) folders.push(subscriptionFolder)
+  
+  return makeBrainfishCollection({
+    name,
+    description: description || schema.info.description || 'GraphQL API',
+    folders,
+    requests: [],
+    variables: [],
+    auth: { authType: 'none', authActive: false },
+    headers: [
+      {
+        key: 'Content-Type',
+        value: 'application/json',
+        active: true,
+        description: 'GraphQL requests use JSON',
+      },
+    ],
+  })
+}
+
+/**
+ * Merge GraphQL collection with existing REST collection
+ */
+export function mergeWithRESTCollection(
+  restCollection: BrainfishCollection,
+  graphqlSchema: GraphQLSchema,
+  graphqlEndpoint: string
+): BrainfishCollection {
+  const graphqlCollection = convertGraphQLToBrainfishCollection(
+    graphqlSchema,
+    'GraphQL',
+    graphqlEndpoint
+  )
+  
+  return {
+    ...restCollection,
+    folders: [...restCollection.folders, graphqlCollection],
+  }
+}

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

@@ -0,0 +1,283 @@
+/**
+ * GraphQL Types for Brainfish API Documentation
+ * 
+ * Types for parsing and representing GraphQL schemas in the documentation system.
+ */
+
+// ============================================================================
+// GraphQL Scalar Types
+// ============================================================================
+
+export type GraphQLScalarType = 
+  | 'String'
+  | 'Int'
+  | 'Float'
+  | 'Boolean'
+  | 'ID'
+  | string // Custom scalars
+
+// ============================================================================
+// GraphQL Type Kinds
+// ============================================================================
+
+export type GraphQLTypeKind = 
+  | 'SCALAR'
+  | 'OBJECT'
+  | 'INPUT_OBJECT'
+  | 'ENUM'
+  | 'INTERFACE'
+  | 'UNION'
+  | 'LIST'
+  | 'NON_NULL'
+
+// ============================================================================
+// GraphQL Type Reference
+// ============================================================================
+
+export interface GraphQLTypeRef {
+  kind: GraphQLTypeKind
+  name: string | null
+  ofType?: GraphQLTypeRef | null
+}
+
+// ============================================================================
+// GraphQL Argument
+// ============================================================================
+
+export interface GraphQLArgument {
+  name: string
+  description: string | null
+  type: GraphQLTypeRef
+  defaultValue: string | null
+  isRequired: boolean
+}
+
+// ============================================================================
+// GraphQL Field
+// ============================================================================
+
+export interface GraphQLField {
+  name: string
+  description: string | null
+  args: GraphQLArgument[]
+  type: GraphQLTypeRef
+  isDeprecated: boolean
+  deprecationReason: string | null
+}
+
+// ============================================================================
+// GraphQL Enum Value
+// ============================================================================
+
+export interface GraphQLEnumValue {
+  name: string
+  description: string | null
+  isDeprecated: boolean
+  deprecationReason: string | null
+}
+
+// ============================================================================
+// GraphQL Input Field
+// ============================================================================
+
+export interface GraphQLInputField {
+  name: string
+  description: string | null
+  type: GraphQLTypeRef
+  defaultValue: string | null
+  isRequired: boolean
+}
+
+// ============================================================================
+// GraphQL Type Definitions
+// ============================================================================
+
+export interface GraphQLScalarTypeDef {
+  kind: 'SCALAR'
+  name: string
+  description: string | null
+}
+
+export interface GraphQLObjectTypeDef {
+  kind: 'OBJECT'
+  name: string
+  description: string | null
+  fields: GraphQLField[]
+  interfaces: string[]
+}
+
+export interface GraphQLInputObjectTypeDef {
+  kind: 'INPUT_OBJECT'
+  name: string
+  description: string | null
+  inputFields: GraphQLInputField[]
+}
+
+export interface GraphQLEnumTypeDef {
+  kind: 'ENUM'
+  name: string
+  description: string | null
+  enumValues: GraphQLEnumValue[]
+}
+
+export interface GraphQLInterfaceTypeDef {
+  kind: 'INTERFACE'
+  name: string
+  description: string | null
+  fields: GraphQLField[]
+  possibleTypes: string[]
+}
+
+export interface GraphQLUnionTypeDef {
+  kind: 'UNION'
+  name: string
+  description: string | null
+  possibleTypes: string[]
+}
+
+export type GraphQLTypeDef = 
+  | GraphQLScalarTypeDef
+  | GraphQLObjectTypeDef
+  | GraphQLInputObjectTypeDef
+  | GraphQLEnumTypeDef
+  | GraphQLInterfaceTypeDef
+  | GraphQLUnionTypeDef
+
+// ============================================================================
+// GraphQL Operation Types
+// ============================================================================
+
+export type GraphQLOperationType = 'query' | 'mutation' | 'subscription'
+
+export interface GraphQLOperation {
+  id: string
+  name: string
+  description: string | null
+  operationType: GraphQLOperationType
+  args: GraphQLArgument[]
+  returnType: GraphQLTypeRef
+  isDeprecated: boolean
+  deprecationReason: string | null
+}
+
+// ============================================================================
+// GraphQL Directive
+// ============================================================================
+
+export interface GraphQLDirective {
+  name: string
+  description: string | null
+  locations: string[]
+  args: GraphQLArgument[]
+}
+
+// ============================================================================
+// GraphQL Schema
+// ============================================================================
+
+export interface GraphQLSchemaInfo {
+  /** Schema description */
+  description: string | null
+  /** Query type name (usually "Query") */
+  queryType: string | null
+  /** Mutation type name (usually "Mutation") */
+  mutationType: string | null
+  /** Subscription type name (usually "Subscription") */
+  subscriptionType: string | null
+}
+
+export interface GraphQLSchema {
+  /** Schema metadata */
+  info: GraphQLSchemaInfo
+  /** All type definitions */
+  types: Record<string, GraphQLTypeDef>
+  /** All directives */
+  directives: GraphQLDirective[]
+  /** Parsed queries */
+  queries: GraphQLOperation[]
+  /** Parsed mutations */
+  mutations: GraphQLOperation[]
+  /** Parsed subscriptions */
+  subscriptions: GraphQLOperation[]
+}
+
+// ============================================================================
+// GraphQL Collection (for integration with existing system)
+// ============================================================================
+
+export interface BrainfishGraphQLRequest {
+  id: string
+  name: string
+  description: string | null
+  operationType: GraphQLOperationType
+  /** The GraphQL query/mutation/subscription string */
+  query: string
+  /** Variables schema */
+  variables: GraphQLArgument[]
+  /** Return type */
+  returnType: GraphQLTypeRef
+  /** Tags for grouping */
+  tags: string[]
+  /** Example variables */
+  exampleVariables?: Record<string, unknown>
+  /** Example response */
+  exampleResponse?: unknown
+}
+
+export interface BrainfishGraphQLCollection {
+  id: string
+  name: string
+  description: string | null
+  /** GraphQL endpoint URL */
+  endpoint: string
+  /** Schema information */
+  schema: GraphQLSchema
+  /** All operations organized */
+  queries: BrainfishGraphQLRequest[]
+  mutations: BrainfishGraphQLRequest[]
+  subscriptions: BrainfishGraphQLRequest[]
+  /** Custom types for reference */
+  types: GraphQLTypeDef[]
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Format a GraphQL type reference as a string
+ * e.g., [String!]! -> "[String!]!"
+ */
+export function formatTypeRef(typeRef: GraphQLTypeRef): string {
+  if (typeRef.kind === 'NON_NULL' && typeRef.ofType) {
+    return `${formatTypeRef(typeRef.ofType)}!`
+  }
+  if (typeRef.kind === 'LIST' && typeRef.ofType) {
+    return `[${formatTypeRef(typeRef.ofType)}]`
+  }
+  return typeRef.name || 'Unknown'
+}
+
+/**
+ * Check if a type is required (non-null at the top level)
+ */
+export function isTypeRequired(typeRef: GraphQLTypeRef): boolean {
+  return typeRef.kind === 'NON_NULL'
+}
+
+/**
+ * Get the base type name from a type reference
+ */
+export function getBaseTypeName(typeRef: GraphQLTypeRef): string {
+  if (typeRef.ofType) {
+    return getBaseTypeName(typeRef.ofType)
+  }
+  return typeRef.name || 'Unknown'
+}
+
+/**
+ * Check if a type is a scalar type
+ */
+export function isScalarType(typeName: string): boolean {
+  return ['String', 'Int', 'Float', 'Boolean', 'ID'].includes(typeName)
+}

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

@@ -0,0 +1,32 @@
+# OpenAPI Parser
+
+This directory contains the OpenAPI parsing logic ported from Hoppscotch.
+
+## Structure
+
+- `index.ts` - Main importer function
+- `validator.ts` - OpenAPI validation logic
+- `dereferencer.ts` - Reference resolution
+- `transformer.ts` - OpenAPI → BrainfishCollection conversion
+- `parsers/` - Version-specific parsers (v2, v3, v31)
+- `extractors/` - Extraction functions (auth, params, headers, body, responses)
+- `example-generators/` - Example generation from schemas
+
+## Dependencies Required
+
+Before implementing, install these dependencies:
+
+```bash
+npm install @apidevtools/swagger-parser openapi-types js-yaml lodash-es
+npm install -D @types/js-yaml @types/lodash-es
+```
+
+## Porting Strategy
+
+1. Copy functions from Hoppscotch's `openapi/index.ts`
+2. Replace `HoppCollection` → `BrainfishCollection`
+3. Replace `HoppRESTRequest` → `BrainfishRESTRequest`
+4. Replace `makeCollection` → `makeBrainfishCollection`
+5. Replace `makeRESTRequest` → `makeBrainfishRESTRequest`
+6. Convert fp-ts to native TypeScript (optional)
+7. Convert Web Worker to Next.js API route or direct function calls

package/renderer/lib/api-docs/parsers/openapi/dereferencer.ts

@@ -0,0 +1,60 @@
+/**
+ * OpenAPI Dereferencer
+ * 
+ * Ported from Hoppscotch's openapi-import-worker.ts
+ * Converts Web Worker pattern to direct function calls for Next.js
+ */
+
+import SwaggerParser from '@apidevtools/swagger-parser'
+import type { OpenAPI } from 'openapi-types'
+
+/**
+ * Dereferences all $ref references in an OpenAPI document
+ * 
+ * @param docs - The OpenAPI document to dereference
+ * @returns Promise resolving to dereferenced OpenAPI document
+ * @throws Error if dereferencing fails
+ */
+export async function dereferenceOpenAPISpec(
+  docs: OpenAPI.Document
+): Promise<OpenAPI.Document> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const dereferenced = await SwaggerParser.dereference(docs as any)
+    return dereferenced as OpenAPI.Document
+  } catch {
+    throw new Error('COULD_NOT_DEREFERENCE')
+  }
+}
+
+/**
+ * Checks if a document has unresolved $ref references
+ * 
+ * @param obj - The object to check
+ * @param visited - Set of visited objects to detect circular references
+ * @returns true if unresolved references are found
+ */
+export function hasUnresolvedRefs(
+  obj: unknown,
+  visited = new WeakSet()
+): boolean {
+  // Handle non-objects or null
+  if (!obj || typeof obj !== 'object') return false
+
+  // Check for circular references
+  if (visited.has(obj)) return false
+
+  // Add current object to visited set
+  visited.add(obj)
+
+  // Check if current object has $ref property
+  if ('$ref' in obj && typeof obj.$ref === 'string') return true
+
+  // Check arrays
+  if (Array.isArray(obj)) {
+    return obj.some((item) => hasUnresolvedRefs(item, visited))
+  }
+
+  // Check object properties
+  return Object.values(obj).some((value) => hasUnresolvedRefs(value, visited))
+}