polen 0.10.0-next.11 → 0.10.0-next.12

package/src/lib/graphql-document/$.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+import { GraphQLDocument } from './$.ts'
+
+describe('GraphQLDocument', () => {
+  describe('analyze', () => {
+    it('should parse a simple query and extract identifiers', () => {
+      const source = `
+        query GetUser($id: ID!) {
+          user(id: $id) {
+            name
+            email
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      expect(result.isValid).toBe(true)
+      expect(result.identifiers.all.length).toBeGreaterThan(0)
+
+      // Should find variable
+      const variables = result.identifiers.byKind.get('Variable') || []
+      expect(variables).toHaveLength(1)
+      expect(variables[0]?.name).toBe('id')
+
+      // Should find fields
+      const fields = result.identifiers.byKind.get('Field') || []
+      expect(fields.length).toBeGreaterThan(0)
+      const fieldNames = fields.map(f => f.name)
+      expect(fieldNames).toContain('user')
+      expect(fieldNames).toContain('name')
+      expect(fieldNames).toContain('email')
+
+      // Should find types
+      const types = result.identifiers.byKind.get('Type') || []
+      expect(types.length).toBeGreaterThan(0)
+      const typeNames = types.map(t => t.name)
+      expect(typeNames).toContain('ID')
+    })
+
+    it('should handle parsing errors gracefully', () => {
+      const invalidSource = `
+        query {
+          user(id: $id {
+            name
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(invalidSource)
+
+      expect(result.isValid).toBe(false)
+      expect(result.identifiers.errors.length).toBeGreaterThan(0)
+    })
+
+    it('should extract context information', () => {
+      const source = `
+        query GetUserPosts($userId: ID!) {
+          user(id: $userId) {
+            posts {
+              title
+              content
+            }
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      const fields = result.identifiers.byKind.get('Field') || []
+      const userField = fields.find(f => f.name === 'user')
+
+      expect(userField?.context.operationType).toBe('query')
+      expect(userField?.context.operationName).toBe('GetUserPosts')
+      expect(userField?.context.selectionPath).toEqual(['user'])
+    })
+
+    it('should track parent types in nested selections', () => {
+      const source = `
+        query {
+          user {
+            posts {
+              title
+            }
+          }
+        }
+      `
+
+      const result = GraphQLDocument.analyze(source)
+
+      const fields = result.identifiers.byKind.get('Field') || []
+      const titleField = fields.find(f => f.name === 'title')
+
+      expect(titleField?.schemaPath).toEqual(['Post', 'title'])
+    })
+  })
+
+  describe('extractIdentifiers', () => {
+    it('should extract identifiers with positions', () => {
+      const source = `query { user { name } }`
+
+      const identifiers = GraphQLDocument.extractIdentifiers(source)
+
+      expect(identifiers.all.length).toBeGreaterThan(0)
+
+      // Each identifier should have position information
+      for (const identifier of identifiers.all) {
+        expect(identifier.position.start).toBeTypeOf('number')
+        expect(identifier.position.end).toBeTypeOf('number')
+        expect(identifier.position.line).toBeGreaterThan(0)
+        expect(identifier.position.column).toBeGreaterThan(0)
+      }
+    })
+
+    it('should create proper index maps', () => {
+      const source = `query { user { name } }`
+
+      const identifiers = GraphQLDocument.extractIdentifiers(source)
+
+      // Should have position index
+      expect(identifiers.byPosition.size).toBeGreaterThan(0)
+
+      // Should have kind index
+      expect(identifiers.byKind.size).toBeGreaterThan(0)
+
+      // All identifiers should be indexed
+      for (const identifier of identifiers.all) {
+        expect(identifiers.byPosition.get(identifier.position.start)).toBe(identifier)
+      }
+    })
+  })
+})

package/src/lib/graphql-document/$.ts

@@ -0,0 +1 @@
+export * as GraphQLDocument from './graphql-document.ts'

package/src/lib/graphql-document/README.md

@@ -0,0 +1,102 @@
+# GraphQL Document Component
+
+Transform static GraphQL code blocks into interactive documentation with hyperlinks, tooltips, and schema validation.
+
+## Overview
+
+The GraphQL Document component enhances markdown code blocks with:
+
+- **Hyperlinked identifiers** - Click to navigate to reference documentation
+- **Hover tooltips** - View type information and descriptions
+- **Schema validation** - Highlight errors and deprecations
+- **Build-time checking** - Catch GraphQL errors during build
+
+## Architecture
+
+The implementation follows a layered architecture:
+
+1. **Analysis Layer** - Parses GraphQL and extracts identifiers
+2. **Schema Integration** - Resolves identifiers against GraphQL schema
+3. **Positioning Engine** - Maps source positions to DOM coordinates
+4. **UI Components** - React components for interactivity
+5. **Orchestration** - Main component tying everything together
+6. **Polen Integration** - Virtual modules and Vite plugin
+
+## Usage
+
+### Basic Setup
+
+1. Import the component in your MDX files:
+
+```typescript
+import { GraphQLDocumentWithSchema } from 'polen/components'
+```
+
+2. Use the component with GraphQL documents:
+
+```mdx
+<GraphQLDocumentWithSchema>
+{`query GetUser($id: ID!) {
+  user(id: $id) {
+    name
+    email
+  }
+}`}
+</GraphQLDocumentWithSchema>
+```
+
+### Component Props
+
+The `GraphQLDocumentWithSchema` component automatically loads the schema from Polen's virtual modules. You can pass options:
+
+```mdx
+<GraphQLDocumentWithSchema 
+  options={{ 
+    debug: true,
+    onNavigate: (url) => console.log('Navigate to:', url)
+  }}
+>
+{`query { user { name } }`}
+</GraphQLDocumentWithSchema>
+```
+
+### React Component
+
+Use the component directly in React:
+
+```tsx
+import { GraphQLDocument } from 'polen/lib/graphql-document'
+
+<GraphQLDocument schema={schema} options={{ debug: true }}>
+  {`query { user { name } }`}
+</GraphQLDocument>
+```
+
+## Implementation Details
+
+### Key Components
+
+- `GraphQLDocument` - Main React component
+- `IdentifierLink` - Interactive overlay for identifiers
+- `HoverTooltip` - Tooltip showing type information
+- `GraphQLDocumentWithSchema` - Wrapper that loads schema from Polen
+- `PolenSchemaResolver` - Schema integration
+
+### Testing
+
+Run tests with:
+
+```bash
+pnpm test:unit src/lib/graphql-document
+```
+
+### Type Safety
+
+Full TypeScript support with strict typing throughout.
+
+## Future Enhancements
+
+- Code folding for large queries
+- Inline query execution
+- Schema diff visualization
+- Export to various formats

package/src/lib/graphql-document/analysis.ts

@@ -0,0 +1,415 @@
+import {
+  type ArgumentNode,
+  type ASTNode,
+  type DirectiveNode,
+  type DocumentNode,
+  type FieldNode,
+  type FragmentDefinitionNode,
+  type GraphQLError,
+  type GraphQLSchema,
+  type OperationDefinitionNode,
+  parse,
+  validate,
+  type VariableDefinitionNode,
+  visit,
+} from 'graphql'
+import type {
+  AnalysisConfig,
+  AnalysisError,
+  AnalysisResult,
+  GraphQLAnalyzer,
+  Identifier,
+  IdentifierContext,
+  IdentifierMap,
+} from './types.ts'
+
+/**
+ * Default GraphQL document analyzer implementation
+ */
+export class DefaultGraphQLAnalyzer implements GraphQLAnalyzer {
+  /**
+   * Parse a GraphQL document string into an AST
+   */
+  parse(source: string): DocumentNode {
+    try {
+      return parse(source, {
+        noLocation: false, // We need location info for positioning
+      })
+    } catch (error) {
+      throw new Error(`Failed to parse GraphQL document: ${error instanceof Error ? error.message : 'Unknown error'}`)
+    }
+  }
+
+  /**
+   * Validate a GraphQL document against a schema
+   */
+  validateAgainstSchema(ast: DocumentNode, schema: GraphQLSchema): GraphQLError[] {
+    return [...validate(schema, ast)]
+  }
+
+  /**
+   * Extract all identifiers from a GraphQL AST
+   */
+  extractIdentifiers(ast: DocumentNode, config: AnalysisConfig = {}): IdentifierMap {
+    const identifiers: Identifier[] = []
+    const errors: AnalysisError[] = []
+    const schema = config.schema
+
+    // Context tracking during traversal
+    let currentOperationType: 'query' | 'mutation' | 'subscription' | undefined
+    let currentOperationName: string | undefined
+    let currentFragment: string | undefined
+    let selectionPath: string[] = []
+    let parentTypes: string[] = []
+
+    // Helper function to create context
+    const createContext = (): IdentifierContext => {
+      return {
+        operationType: currentOperationType,
+        operationName: currentOperationName,
+        inFragment: currentFragment,
+        selectionPath: [...selectionPath],
+      }
+    }
+
+    visit(ast, {
+      OperationDefinition: {
+        enter: (node: OperationDefinitionNode) => {
+          currentOperationType = node.operation
+          currentOperationName = node.name?.value
+          selectionPath = []
+
+          // Set the root type based on operation type
+          if (schema) {
+            if (node.operation === 'query' && schema.getQueryType()) {
+              parentTypes = [schema.getQueryType()!.name]
+            } else if (node.operation === 'mutation' && schema.getMutationType()) {
+              parentTypes = [schema.getMutationType()!.name]
+            } else if (node.operation === 'subscription' && schema.getSubscriptionType()) {
+              parentTypes = [schema.getSubscriptionType()!.name]
+            } else {
+              parentTypes = []
+            }
+          } else {
+            // Fallback to default root type names
+            if (node.operation === 'query') {
+              parentTypes = ['Query']
+            } else if (node.operation === 'mutation') {
+              parentTypes = ['Mutation']
+            } else if (node.operation === 'subscription') {
+              parentTypes = ['Subscription']
+            } else {
+              parentTypes = []
+            }
+          }
+        },
+        leave: () => {
+          currentOperationType = undefined
+          currentOperationName = undefined
+          parentTypes = []
+        },
+      },
+
+      FragmentDefinition: {
+        enter: (node: FragmentDefinitionNode) => {
+          currentFragment = node.name.value
+          selectionPath = []
+          parentTypes = [node.typeCondition.name.value]
+
+          // Add fragment name as identifier
+          this.addIdentifier(identifiers, {
+            name: node.name.value,
+            kind: 'Fragment',
+            position: this.getPosition(node.name),
+            schemaPath: [node.name.value],
+            context: createContext(),
+          })
+
+          // Add type condition as identifier
+          this.addIdentifier(identifiers, {
+            name: node.typeCondition.name.value,
+            kind: 'Type',
+            position: this.getPosition(node.typeCondition.name),
+            schemaPath: [node.typeCondition.name.value],
+            context: createContext(),
+          })
+        },
+        leave: () => {
+          currentFragment = undefined
+          parentTypes = []
+        },
+      },
+
+      Field: {
+        enter: (node: FieldNode) => {
+          const fieldName = node.name.value
+          const parentType = parentTypes[parentTypes.length - 1]
+
+          selectionPath.push(fieldName)
+
+          this.addIdentifier(identifiers, {
+            name: fieldName,
+            kind: 'Field',
+            position: this.getPosition(node.name),
+            parentType,
+            schemaPath: parentType ? [parentType, fieldName] : [fieldName],
+            context: createContext(),
+          })
+
+          // Track parent type for nested selections
+          // Resolve the field's return type from schema if available
+          let pushedType = false
+          if (schema && parentType) {
+            const type = schema.getType(parentType)
+            if (type && ('getFields' in type)) {
+              const fields = (type as any).getFields()
+              const field = fields[fieldName]
+              if (field) {
+                // Get the base type name (unwrap NonNull and List wrappers)
+                let fieldType = field.type
+                while (fieldType.ofType) {
+                  fieldType = fieldType.ofType
+                }
+                if (fieldType.name) {
+                  parentTypes.push(fieldType.name)
+                  pushedType = true
+                }
+              }
+            }
+          } else if (this.isObjectField(fieldName)) {
+            // Fallback to inference if no schema
+            const inferredType = this.inferReturnType(parentType, fieldName)
+            parentTypes.push(inferredType)
+            pushedType = true
+          } // Store whether we pushed a type for this field
+
+          ;(node as any)._pushedType = pushedType
+        },
+        leave: (node: FieldNode) => {
+          selectionPath.pop()
+
+          // Remove parent type if we added one in enter
+          if ((node as any)._pushedType) {
+            parentTypes.pop()
+          }
+        },
+      },
+
+      Argument: {
+        enter: (node: ArgumentNode) => {
+          const argName = node.name.value
+          const parentType = parentTypes[parentTypes.length - 1]
+          const fieldName = selectionPath[selectionPath.length - 1]
+
+          this.addIdentifier(identifiers, {
+            name: argName,
+            kind: 'Argument',
+            position: this.getPosition(node.name),
+            parentType,
+            schemaPath: parentType && fieldName
+              ? [parentType, fieldName, argName]
+              : [argName],
+            context: createContext(),
+          })
+        },
+      },
+
+      VariableDefinition: {
+        enter: (node: VariableDefinitionNode) => {
+          this.addIdentifier(identifiers, {
+            name: node.variable.name.value,
+            kind: 'Variable',
+            position: this.getPosition(node.variable.name),
+            schemaPath: [node.variable.name.value],
+            context: createContext(),
+          })
+
+          // Also add the type reference
+          const typeName = this.extractTypeName(node.type)
+          if (typeName) {
+            this.addIdentifier(identifiers, {
+              name: typeName,
+              kind: 'Type',
+              position: this.getTypePosition(node.type),
+              schemaPath: [typeName],
+              context: createContext(),
+            })
+          }
+        },
+      },
+
+      Directive: {
+        enter: (node: DirectiveNode) => {
+          this.addIdentifier(identifiers, {
+            name: node.name.value,
+            kind: 'Directive',
+            position: this.getPosition(node.name),
+            schemaPath: [node.name.value],
+            context: createContext(),
+          })
+        },
+      },
+    })
+
+    return this.createIdentifierMap(identifiers, errors)
+  }
+
+  /**
+   * Perform complete analysis of a GraphQL document
+   */
+  analyze(source: string, config: AnalysisConfig = {}): AnalysisResult {
+    try {
+      const ast = this.parse(source)
+      const identifiers = this.extractIdentifiers(ast, config)
+
+      let validationErrors: GraphQLError[] = []
+      if (config.validateAgainstSchema && config.schema) {
+        validationErrors = this.validateAgainstSchema(ast, config.schema)
+      }
+
+      return {
+        ast,
+        identifiers,
+        isValid: validationErrors.length === 0,
+        errors: validationErrors,
+      }
+    } catch (error) {
+      return {
+        ast: { kind: 'Document', definitions: [] } as DocumentNode,
+        identifiers: this.createIdentifierMap([], [{
+          message: error instanceof Error ? error.message : 'Unknown parsing error',
+          severity: 'error',
+        }]),
+        isValid: false,
+        errors: [],
+      }
+    }
+  }
+
+  // Private helper methods
+
+  private addIdentifier(identifiers: Identifier[], identifier: Identifier): void {
+    identifiers.push(identifier)
+  }
+
+  private getPosition(node: ASTNode): Identifier['position'] {
+    const loc = node.loc
+    if (!loc) {
+      return { start: 0, end: 0, line: 1, column: 1 }
+    }
+
+    return {
+      start: loc.start,
+      end: loc.end,
+      line: loc.startToken.line,
+      column: loc.startToken.column,
+    }
+  }
+
+  private getTypePosition(node: ASTNode): Identifier['position'] {
+    // For type nodes, we need to extract the base type name position
+    // This is a simplified implementation
+    return this.getPosition(node)
+  }
+
+  private extractTypeName(typeNode: any): string | null {
+    // Recursively extract the base type name from wrapped types (NonNull, List)
+    if (typeNode.kind === 'NamedType') {
+      return typeNode.name.value
+    }
+    if (typeNode.kind === 'NonNullType' || typeNode.kind === 'ListType') {
+      return this.extractTypeName(typeNode.type)
+    }
+    return null
+  }
+
+  private isObjectField(fieldName: string): boolean {
+    // This is only used as a fallback when no schema is available
+    // Common patterns for object-returning fields
+    const objectFieldPatterns = [
+      'user',
+      'users',
+      'post',
+      'posts',
+      'comment',
+      'comments',
+      'profile',
+      'settings',
+      'organization',
+      'project',
+      'target',
+      'member',
+      'members',
+      'node',
+      'nodes',
+      'edge',
+      'edges',
+    ]
+    return objectFieldPatterns.some(pattern => fieldName.toLowerCase().includes(pattern))
+  }
+
+  private inferReturnType(parentType: string | undefined, fieldName: string): string {
+    // Simplified type inference - in real implementation would use schema
+    if (fieldName === 'user') return 'User'
+    if (fieldName === 'posts') return 'Post'
+    if (fieldName === 'comments') return 'Comment'
+    return fieldName.charAt(0).toUpperCase() + fieldName.slice(1)
+  }
+
+  private createContext(
+    operationType?: 'query' | 'mutation' | 'subscription',
+    operationName?: string,
+    inFragment?: string,
+    selectionPath: string[] = [],
+  ): IdentifierContext {
+    return {
+      operationType,
+      operationName,
+      inFragment,
+      selectionPath: [...selectionPath],
+    }
+  }
+
+  private createIdentifierMap(identifiers: Identifier[], errors: AnalysisError[]): IdentifierMap {
+    const byPosition = new Map<number, Identifier>()
+    const byKind = new Map<Identifier['kind'], Identifier[]>()
+
+    for (const identifier of identifiers) {
+      // Index by position
+      byPosition.set(identifier.position.start, identifier)
+
+      // Group by kind
+      if (!byKind.has(identifier.kind)) {
+        byKind.set(identifier.kind, [])
+      }
+      byKind.get(identifier.kind)!.push(identifier)
+    }
+
+    return {
+      byPosition,
+      byKind,
+      errors,
+      all: identifiers,
+    }
+  }
+}
+
+/**
+ * Default analyzer instance
+ */
+export const analyzer = new DefaultGraphQLAnalyzer()
+
+/**
+ * Convenience function to analyze a GraphQL document
+ */
+export const analyze = (source: string, config?: AnalysisConfig): AnalysisResult => {
+  return analyzer.analyze(source, config)
+}
+
+/**
+ * Convenience function to extract identifiers from a GraphQL document
+ */
+export const extractIdentifiers = (source: string, config?: AnalysisConfig): IdentifierMap => {
+  const ast = analyzer.parse(source)
+  return analyzer.extractIdentifiers(ast, config)
+}