polen 0.10.0-next.9 → 0.10.0

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.js'
+
+/**
+ * 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,265 @@
+import type { React } from '#dep/react/index'
+import { React as ReactHooks } from '#dep/react/index'
+import type { GraphQLSchema } from 'graphql'
+import { useNavigate } from 'react-router'
+import { analyze } from '../analysis.js'
+import { useTooltipState } from '../hooks/use-tooltip-state.js'
+import { createSimplePositionCalculator } from '../positioning-simple.js'
+import { createPolenSchemaResolver } from '../schema-integration.js'
+import type { Identifier } from '../types.js'
+import { graphqlDocumentStyles } from './graphql-document-styles.js'
+import { IdentifierLink } from './IdentifierLink.js'
+
+/**
+ * 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
+  /** Custom render function for the code block */
+  renderCode?: () => React.ReactNode
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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 = {},
+}) => {
+  const {
+    debug = false,
+    plain = false,
+    onNavigate,
+    validate = true,
+    className = ``,
+    renderCode,
+  } = options
+
+  const navigate = useNavigate()
+  const handleNavigate = onNavigate || ((url: string) => navigate(url))
+
+  // Container ref for positioning calculations
+  const containerRef = ReactHooks.useRef<HTMLDivElement>(null)
+  const [isReady, setIsReady] = ReactHooks.useState(false)
+
+  // Use tooltip state management
+  const tooltipState = useTooltipState({
+    showDelay: 300,
+    hideDelay: 200, // Increased for smoother experience
+    allowMultiplePins: true,
+  })
+
+  // Handle escape key to unpin all
+  ReactHooks.useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === `Escape`) {
+        tooltipState.unpinAll()
+      }
+    }
+
+    document.addEventListener(`keydown`, handleKeyDown)
+    return () => {
+      document.removeEventListener(`keydown`, handleKeyDown)
+    }
+  }, [tooltipState])
+
+  // Layer 1: Parse and analyze
+  const analysisResult = ReactHooks.useMemo(() => {
+    if (plain) return null
+    const result = analyze(children, { schema })
+    // Debug logging handled by debug prop
+    return result
+  }, [children, plain, schema, debug])
+
+  // Layer 2: Schema resolution
+  const resolver = ReactHooks.useMemo(() => {
+    if (!schema || plain) return null
+    return createPolenSchemaResolver(schema)
+  }, [schema, plain])
+
+  const resolutions = ReactHooks.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 = ReactHooks.useMemo(() => {
+    if (plain) return null
+    return createSimplePositionCalculator()
+  }, [plain])
+
+  const [positions, setPositions] = ReactHooks.useState<Map<string, { position: any; identifier: Identifier }>>(
+    new Map(),
+  )
+
+  // Prepare code block and calculate positions after render
+  ReactHooks.useEffect(() => {
+    if (!containerRef.current || !analysisResult || !positionCalculator || plain) {
+      // Skip position calculation - debug handled by debug prop
+      return
+    }
+
+    // Get the code element within the container
+    const codeElement = containerRef.current.querySelector(`pre.code-block code`)
+      || containerRef.current.querySelector(`pre code`)
+      || containerRef.current.querySelector(`code`)
+    if (!codeElement) {
+      // No code element found - skip
+      return
+    }
+
+    // Prepare the code block (wrap identifiers)
+    const identifiers = Array.from(analysisResult.identifiers.byPosition.values())
+    // Prepare code block with identifiers
+    positionCalculator.prepareCodeBlock(codeElement, identifiers)
+
+    // Get positions after DOM update
+    requestAnimationFrame(() => {
+      // Pass containerRef.current as the reference element for positioning
+      if (containerRef.current) {
+        const newPositions = positionCalculator.getIdentifierPositions(codeElement, containerRef.current)
+        // Position calculation complete
+        setPositions(newPositions)
+        setIsReady(true)
+      }
+    })
+  }, [analysisResult, positionCalculator, plain])
+
+  // Handle resize events with debouncing
+  ReactHooks.useEffect(() => {
+    if (!containerRef.current || !positionCalculator || plain) return
+
+    let resizeTimer: NodeJS.Timeout
+    const handleResize = () => {
+      clearTimeout(resizeTimer)
+      resizeTimer = setTimeout(() => {
+        const codeElement = containerRef.current?.querySelector(`pre.code-block code`)
+          || containerRef.current?.querySelector(`pre code`)
+          || containerRef.current?.querySelector(`code`)
+        if (codeElement && containerRef.current) {
+          const newPositions = positionCalculator.getIdentifierPositions(codeElement, containerRef.current)
+          setPositions(newPositions)
+        }
+      }, 100) // Debounce resize events
+    }
+
+    window.addEventListener(`resize`, handleResize)
+    return () => {
+      clearTimeout(resizeTimer)
+      window.removeEventListener(`resize`, handleResize)
+    }
+  }, [positionCalculator, plain])
+
+  // Validation errors
+  const validationErrors = ReactHooks.useMemo(() => {
+    if (!validate || !analysisResult || !schema) return []
+    return analysisResult.errors
+  }, [validate, analysisResult, schema])
+
+  return (
+    <>
+      <style dangerouslySetInnerHTML={{ __html: graphqlDocumentStyles }} />
+      <div
+        ref={containerRef}
+        className={`graphql-document ${className} ${debug ? `graphql-debug-mode` : ``} ${
+          !isReady && !plain ? `graphql-loading` : ``
+        }`}
+        data-testid='graphql-document'
+      >
+        {/* Base code block */}
+        {renderCode
+          ? (
+            renderCode()
+          )
+          : (
+            <pre className='code-block'>
+            <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={tooltipState.isOpen(id)}
+                  isPinned={tooltipState.isPinned(id)}
+                  onHoverStart={() => {
+                    tooltipState.onHoverStart(id)
+                  }}
+                  onHoverEnd={() => {
+                    tooltipState.onHoverEnd(id)
+                  }}
+                  onTogglePin={() => {
+                    tooltipState.onTogglePin(id)
+                  }}
+                  onTooltipHover={() => {
+                    tooltipState.onTooltipHover(id)
+                  }}
+                />
+              )
+            })}
+          </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>
+    </>
+  )
+}