polen 0.10.0-next.10 → 0.10.0-next.12

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)
+}

package/src/lib/graphql-document/components/GraphQLDocument.tsx

@@ -0,0 +1,284 @@
+import type { React } from '#dep/react/index'
+import type { GraphQLSchema } from 'graphql'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { useNavigate } from 'react-router'
+import { analyze } from '../analysis.ts'
+import { createSimplePositionCalculator } from '../positioning-simple.ts'
+import { createPolenSchemaResolver } from '../schema-integration.ts'
+import type { Identifier } from '../types.ts'
+import { hoverTooltipStyles } from './HoverTooltip.tsx'
+import { IdentifierLink } from './IdentifierLink.tsx'
+import { identifierLinkStyles } from './IdentifierLink.tsx'
+
+/**
+ * Options for the GraphQL document component
+ */
+export interface GraphQLDocumentOptions {
+  /** Whether to show debug overlays */
+  debug?: boolean
+  /** Whether to disable interactive features */
+  plain?: boolean
+  /** Custom navigation handler */
+  onNavigate?: (url: string) => void
+  /** Whether to validate against schema */
+  validate?: boolean
+  /** Custom class name for the container */
+  className?: string
+}
+
+/**
+ * Props for the GraphQL document component
+ */
+export interface GraphQLDocumentProps {
+  /** The GraphQL document source code */
+  children: string
+  /** GraphQL schema for validation and linking */
+  schema?: GraphQLSchema
+  /** Component options */
+  options?: GraphQLDocumentOptions
+  /** Pre-rendered Shiki HTML (from build time) */
+  highlightedHtml?: string
+}
+
+/**
+ * Interactive GraphQL document component
+ *
+ * Transforms static GraphQL code blocks into interactive documentation
+ * with hyperlinks, tooltips, and schema validation.
+ */
+export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
+  children,
+  schema,
+  options = {},
+  highlightedHtml,
+}) => {
+  const {
+    debug = false,
+    plain = false,
+    onNavigate,
+    validate = true,
+    className = '',
+  } = options
+
+  const navigate = useNavigate()
+  const handleNavigate = onNavigate || ((url: string) => navigate(url))
+
+  // Container ref for positioning calculations
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [isReady, setIsReady] = useState(false)
+  const [openTooltipId, setOpenTooltipId] = useState<string | null>(null)
+
+  // Handle click outside to close tooltips
+  useEffect(() => {
+    if (!openTooltipId) return
+
+    const handleClickOutside = (event: MouseEvent) => {
+      // Check if click is outside the tooltip and identifier links
+      const target = event.target as HTMLElement
+
+      // Don't close if clicking on an identifier link or tooltip
+      if (
+        target.closest('.graphql-identifier-overlay')
+        || target.closest('.graphql-hover-tooltip')
+      ) {
+        return
+      }
+
+      // Close the tooltip
+      setOpenTooltipId(null)
+    }
+
+    // Add event listener
+    document.addEventListener('mousedown', handleClickOutside)
+
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside)
+    }
+  }, [openTooltipId])
+
+  // Layer 1: Parse and analyze
+  const analysisResult = useMemo(() => {
+    if (plain) return null
+    const result = analyze(children, { schema })
+    return result
+  }, [children, plain, schema])
+
+  // Layer 2: Schema resolution
+  const resolver = useMemo(() => {
+    if (!schema || plain) return null
+    return createPolenSchemaResolver(schema)
+  }, [schema, plain])
+
+  const resolutions = useMemo(() => {
+    if (!analysisResult || !resolver) {
+      return new Map()
+    }
+
+    const results = new Map()
+    for (const [position, identifier] of analysisResult.identifiers.byPosition) {
+      const resolution = resolver.resolveIdentifier(identifier)
+      if (resolution) {
+        results.set(position, resolution)
+      }
+    }
+    return results
+  }, [analysisResult, resolver])
+
+  // Layer 3: Position calculation
+  const positionCalculator = useMemo(() => {
+    if (plain) return null
+    return createSimplePositionCalculator()
+  }, [plain])
+
+  const [positions, setPositions] = useState<Map<string, { position: any; identifier: Identifier }>>(new Map())
+
+  // Prepare code block and calculate positions after render
+  useEffect(() => {
+    if (!containerRef.current || !analysisResult || !positionCalculator || plain) {
+      return
+    }
+
+    // Get the code element within the container
+    const codeElement = containerRef.current.querySelector('pre.shiki code')
+      || containerRef.current.querySelector('pre code')
+      || containerRef.current.querySelector('code')
+    if (!codeElement) {
+      return
+    }
+
+    // Prepare the code block (wrap identifiers)
+    const identifiers = Array.from(analysisResult.identifiers.byPosition.values())
+    positionCalculator.prepareCodeBlock(codeElement as Element, identifiers)
+
+    // Get positions after DOM update
+    requestAnimationFrame(() => {
+      // Pass containerRef.current as the reference element for positioning
+      if (containerRef.current) {
+        const newPositions = positionCalculator.getIdentifierPositions(codeElement as Element, containerRef.current)
+        setPositions(newPositions)
+        setIsReady(true)
+      }
+    })
+  }, [analysisResult, positionCalculator, plain, highlightedHtml])
+
+  // Handle resize events
+  useEffect(() => {
+    if (!containerRef.current || !positionCalculator || plain) return
+
+    const handleResize = () => {
+      const codeElement = containerRef.current?.querySelector('pre.shiki code')
+        || containerRef.current?.querySelector('pre code')
+        || containerRef.current?.querySelector('code')
+      if (codeElement && containerRef.current) {
+        const newPositions = positionCalculator.getIdentifierPositions(codeElement as Element, containerRef.current)
+        setPositions(newPositions)
+      }
+    }
+
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [positionCalculator, plain])
+
+  // Validation errors
+  const validationErrors = useMemo(() => {
+    if (!validate || !analysisResult || !schema) return []
+    return analysisResult.errors
+  }, [validate, analysisResult, schema])
+
+  return (
+    <>
+      {/* Inject styles */}
+      <style dangerouslySetInnerHTML={{ __html: identifierLinkStyles + '\n' + hoverTooltipStyles }} />
+
+      <div
+        ref={containerRef}
+        className={`graphql-document ${className} ${debug ? 'graphql-debug-mode' : ''}`}
+        style={{ position: 'relative' }}
+      >
+        {/* Base syntax highlighting */}
+        {highlightedHtml ? <div dangerouslySetInnerHTML={{ __html: highlightedHtml }} /> : (
+          <pre className='shiki'>
+            <code>{children}</code>
+          </pre>
+        )}
+
+        {/* Interactive overlay layer */}
+        {!plain && isReady && (
+          <div className='graphql-interaction-layer' style={{ pointerEvents: 'none' }}>
+            {Array.from(positions.entries()).map(([id, { position, identifier }]) => {
+              const startPos = identifier.position.start
+              const resolution = resolutions.get(startPos)
+
+              if (!resolution) return null
+
+              return (
+                <IdentifierLink
+                  key={id}
+                  identifier={identifier}
+                  resolution={resolution}
+                  position={position}
+                  onNavigate={handleNavigate}
+                  debug={debug}
+                  isOpen={openTooltipId === id}
+                  onToggle={(open) => setOpenTooltipId(open ? id : null)}
+                />
+              )
+            })}
+          </div>
+        )}
+
+        {/* Validation errors overlay */}
+        {validationErrors.length > 0 && (
+          <div className='graphql-validation-errors'>
+            {validationErrors.map((error: any, index: number) => (
+              <div key={index} className='graphql-error'>
+                {error.message}
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </>
+  )
+}
+
+/**
+ * Default styles for the GraphQL document component
+ */
+export const graphqlDocumentStyles = `
+.graphql-document {
+  position: relative;
+}
+
+.graphql-interaction-layer {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  pointer-events: none;
+}
+
+.graphql-interaction-layer > * {
+  pointer-events: auto;
+}
+
+.graphql-validation-errors {
+  margin-top: 1rem;
+  padding: 0.5rem;
+  background-color: var(--red-2);
+  border: 1px solid var(--red-6);
+  border-radius: 4px;
+}
+
+.graphql-error {
+  color: var(--red-11);
+  font-size: 0.875rem;
+  margin: 0.25rem 0;
+}
+
+.graphql-debug-mode [data-graphql-id] {
+  background-color: rgba(59, 130, 246, 0.1);
+  outline: 1px solid rgba(59, 130, 246, 0.3);
+}
+`