polen 0.10.0-next.11 → 0.10.0-next.13

package/src/lib/graphql-document/positioning-simple.ts

@@ -0,0 +1,271 @@
+/**
+ * Layer 3: Simplified Positioning & Layout Engine
+ *
+ * Maps GraphQL AST positions to DOM coordinates for overlay placement.
+ * This simplified version focuses on working with Polen's existing infrastructure.
+ */
+
+import type { Identifier } from './types.ts'
+
+/**
+ * DOM position for rendering overlays
+ */
+export interface DOMPosition {
+  /** Distance from top of container in pixels */
+  top: number
+  /** Distance from left of container in pixels */
+  left: number
+  /** Width of the identifier in pixels */
+  width: number
+  /** Height of the identifier in pixels */
+  height: number
+}
+
+/**
+ * Position calculation result
+ */
+export interface PositionResult {
+  /** The calculated DOM position */
+  position: DOMPosition
+  /** The identifier this position is for */
+  identifier: Identifier
+}
+
+/**
+ * Simplified position calculator for Shiki-rendered code
+ *
+ * This version uses a more straightforward approach:
+ * 1. Find the line element by line number
+ * 2. Search for the identifier text within that line
+ * 3. Create a span around the identifier for positioning
+ *
+ * This approach modifies the DOM but is more reliable for testing
+ * and works well with React's reconciliation.
+ */
+export class SimplePositionCalculator {
+  /**
+   * Prepare a code block for positioning by wrapping identifiers in spans
+   */
+  prepareCodeBlock(
+    containerElement: Element,
+    identifiers: Identifier[],
+  ): void {
+    // Sort all identifiers by position (right to left, bottom to top)
+    const sortedIdentifiers = [...identifiers].sort((a, b) => {
+      // Sort by line first (bottom to top)
+      if (a.position.line !== b.position.line) {
+        return b.position.line - a.position.line
+      }
+      // Then by column (right to left)
+      return b.position.column - a.position.column
+    })
+
+    // Process all identifiers
+    let wrappedCount = 0
+    for (const identifier of sortedIdentifiers) {
+      const wrapped = this.wrapIdentifier(containerElement, identifier)
+      if (wrapped) wrappedCount++
+    }
+  }
+
+  /**
+   * Get positions of all wrapped identifiers
+   */
+  getIdentifierPositions(
+    containerElement: Element,
+    relativeToElement?: Element,
+  ): Map<string, PositionResult> {
+    const results = new Map<string, PositionResult>()
+
+    // Find all wrapped identifiers
+    const wrappedIdentifiers = containerElement.querySelectorAll('[data-graphql-id]')
+
+    // Use the provided element for relative positioning, or the container itself
+    const referenceElement = relativeToElement || containerElement
+
+    for (const element of wrappedIdentifiers) {
+      const id = element.getAttribute('data-graphql-id')
+      if (!id) continue
+
+      // Get position relative to the reference element
+      const referenceRect = referenceElement.getBoundingClientRect()
+      const elementRect = element.getBoundingClientRect()
+
+      const position: DOMPosition = {
+        top: elementRect.top - referenceRect.top,
+        left: elementRect.left - referenceRect.left,
+        width: elementRect.width,
+        height: elementRect.height,
+      }
+
+      // Reconstruct identifier from data attributes
+      const identifier: Identifier = {
+        name: element.getAttribute('data-graphql-name') || '',
+        kind: (element.getAttribute('data-graphql-kind') || 'Field') as Identifier['kind'],
+        position: {
+          start: parseInt(element.getAttribute('data-graphql-start') || '0'),
+          end: parseInt(element.getAttribute('data-graphql-end') || '0'),
+          line: parseInt(element.getAttribute('data-graphql-line') || '1'),
+          column: parseInt(element.getAttribute('data-graphql-column') || '1'),
+        },
+        schemaPath: (element.getAttribute('data-graphql-path') || '').split(',').filter(Boolean),
+        context: { selectionPath: [] },
+      }
+
+      results.set(id, { position, identifier })
+    }
+
+    return results
+  }
+
+  /**
+   * Wrap an identifier in a span for positioning
+   * Returns true if the identifier was successfully wrapped
+   */
+  private wrapIdentifier(containerElement: Element, identifier: Identifier): boolean {
+    const walker = document.createTreeWalker(
+      containerElement,
+      NodeFilter.SHOW_TEXT,
+      null,
+    )
+
+    let currentLine = 1
+    let currentColumn = 1
+    let node: Node | null
+
+    while (node = walker.nextNode()) {
+      const textNode = node as Text
+      const text = textNode.textContent || ''
+
+      // Check if already wrapped
+      if (textNode.parentElement?.hasAttribute('data-graphql-id')) {
+        // Update position tracking and continue
+        for (const char of text) {
+          if (char === '\n') {
+            currentLine++
+            currentColumn = 1
+          } else {
+            currentColumn++
+          }
+        }
+        continue
+      }
+
+      // Track position in the text
+      let textIndex = 0
+      while (textIndex < text.length) {
+        // Check if we're at the identifier's position
+        if (
+          currentLine === identifier.position.line
+          && currentColumn === identifier.position.column
+        ) {
+          // Verify it's actually our identifier
+          const remainingText = text.substring(textIndex)
+          if (remainingText.startsWith(identifier.name)) {
+            // Create a unique ID for this identifier
+            const id = `${identifier.position.start}-${identifier.name}-${identifier.kind}`
+
+            // Split the text node and wrap the identifier
+            const before = text.substring(0, textIndex)
+            const after = text.substring(textIndex + identifier.name.length)
+
+            const span = document.createElement('span')
+            span.setAttribute('data-graphql-id', id)
+            span.setAttribute('data-graphql-name', identifier.name)
+            span.setAttribute('data-graphql-kind', identifier.kind)
+            span.setAttribute('data-graphql-start', String(identifier.position.start))
+            span.setAttribute('data-graphql-end', String(identifier.position.end))
+            span.setAttribute('data-graphql-line', String(identifier.position.line))
+            span.setAttribute('data-graphql-column', String(identifier.position.column))
+            span.setAttribute('data-graphql-path', identifier.schemaPath.join(','))
+            span.textContent = identifier.name
+
+            const parent = textNode.parentNode!
+
+            if (before) {
+              parent.insertBefore(document.createTextNode(before), textNode)
+            }
+
+            parent.insertBefore(span, textNode)
+
+            if (after) {
+              parent.insertBefore(document.createTextNode(after), textNode)
+            }
+
+            parent.removeChild(textNode)
+            return true
+          }
+        }
+
+        // Update position tracking
+        const char = text[textIndex]
+        if (char === '\n') {
+          currentLine++
+          currentColumn = 1
+        } else {
+          currentColumn++
+        }
+        textIndex++
+      }
+    }
+
+    return false // Identifier not found
+  }
+}
+
+/**
+ * Create invisible overlay for a position
+ */
+export const createSimpleOverlay = (
+  position: DOMPosition,
+  identifier: Identifier,
+  options?: {
+    onClick?: (identifier: Identifier) => void
+    onHover?: (identifier: Identifier, event: MouseEvent) => void
+    className?: string
+  },
+): HTMLElement => {
+  const overlay = document.createElement('div')
+
+  // Base styles for positioning
+  overlay.style.position = 'absolute'
+  overlay.style.top = `${position.top}px`
+  overlay.style.left = `${position.left}px`
+  overlay.style.width = `${position.width}px`
+  overlay.style.height = `${position.height}px`
+  overlay.style.cursor = 'pointer'
+  overlay.style.zIndex = '10'
+
+  // Add custom class if provided
+  if (options?.className) {
+    overlay.className = options.className
+  }
+
+  // Data attributes
+  overlay.setAttribute('data-graphql-overlay', 'true')
+  overlay.setAttribute('data-graphql-name', identifier.name)
+  overlay.setAttribute('data-graphql-kind', identifier.kind)
+
+  // Event handlers
+  if (options?.onClick) {
+    overlay.addEventListener('click', (e) => {
+      e.preventDefault()
+      options.onClick!(identifier)
+    })
+  }
+
+  if (options?.onHover) {
+    overlay.addEventListener('mouseenter', (e) => {
+      options.onHover!(identifier, e)
+    })
+  }
+
+  return overlay
+}
+
+/**
+ * Factory function for position calculator
+ */
+export const createSimplePositionCalculator = (): SimplePositionCalculator => {
+  return new SimplePositionCalculator()
+}

package/src/lib/graphql-document/schema-context.tsx

@@ -0,0 +1,20 @@
+import type { GraphQLSchema } from 'graphql'
+import React from 'react'
+
+export const GraphQLSchemaContext = React.createContext<GraphQLSchema | null>(null)
+
+export const useGraphQLSchema = () => {
+  const schema = React.useContext(GraphQLSchemaContext)
+  return schema
+}
+
+export const GraphQLSchemaProvider: React.FC<React.PropsWithChildren<{ schema: GraphQLSchema | null }>> = ({
+  children,
+  schema,
+}) => {
+  return (
+    <GraphQLSchemaContext.Provider value={schema}>
+      {children}
+    </GraphQLSchemaContext.Provider>
+  )
+}

package/src/lib/graphql-document/schema-integration-example.ts

@@ -0,0 +1,341 @@
+/**
+ * Example usage of Schema Integration (Layer 2)
+ *
+ * Demonstrates how the schema integration layer resolves GraphQL identifiers
+ * against actual schemas, extracts documentation, and generates reference URLs.
+ */
+
+import { buildSchema } from 'graphql'
+import { analyzeWithSchema, createPolenSchemaResolver } from './schema-integration.ts'
+
+// Example schema - typical GraphQL API
+const pokemonSchema = buildSchema(`
+  """
+  A Pokémon character
+  """
+  type Pokemon {
+    """
+    The Pokémon's unique identifier
+    """
+    id: ID!
+    
+    """
+    The Pokémon's name
+    """
+    name: String!
+    
+    """
+    The Pokémon's type (e.g., Electric, Fire, Water)
+    """
+    type: String!
+    
+    """
+    The Pokémon's abilities
+    """
+    abilities(
+      """
+      Maximum number of abilities to return
+      """
+      first: Int = 5
+    ): [Ability!]!
+    
+    """
+    @deprecated Use evolutionChain instead
+    """
+    evolutions: [Pokemon!] @deprecated(reason: "Use evolutionChain instead")
+  }
+
+  """
+  A special ability that Pokémon can have
+  """
+  type Ability {
+    id: ID!
+    name: String!
+    description: String
+    isHidden: Boolean!
+  }
+
+  type Query {
+    """
+    Get a Pokémon by ID
+    """
+    pokemon(id: ID!): Pokemon
+    
+    """
+    Search for Pokémon by name
+    """
+    searchPokemon(query: String!): [Pokemon!]!
+  }
+`)
+
+// Example GraphQL query with various constructs
+const exampleQuery = `
+  query GetPokemonDetails($pokemonId: ID!, $abilityLimit: Int = 3) {
+    pokemon(id: $pokemonId) {
+      id
+      name
+      type
+      abilities(first: $abilityLimit) {
+        name
+        description
+        isHidden
+      }
+      evolutions  # This field is deprecated
+      invalidField  # This field doesn't exist
+    }
+  }
+`
+
+/**
+ * Demonstrate basic schema resolution
+ */
+export const demonstrateSchemaResolution = () => {
+  console.log('🔗 Schema Integration Demo\n')
+
+  const resolver = createPolenSchemaResolver(pokemonSchema)
+
+  // Example identifiers (normally extracted from AST)
+  const testIdentifiers = [
+    {
+      name: 'Pokemon',
+      kind: 'Type' as const,
+      position: { start: 50, end: 57, line: 3, column: 5 },
+      schemaPath: ['Pokemon'],
+      context: { selectionPath: [] },
+    },
+    {
+      name: 'name',
+      kind: 'Field' as const,
+      position: { start: 75, end: 79, line: 4, column: 7 },
+      parentType: 'Pokemon',
+      schemaPath: ['Pokemon', 'name'],
+      context: { selectionPath: ['pokemon', 'name'] },
+    },
+    {
+      name: 'evolutions',
+      kind: 'Field' as const,
+      position: { start: 150, end: 160, line: 9, column: 7 },
+      parentType: 'Pokemon',
+      schemaPath: ['Pokemon', 'evolutions'],
+      context: { selectionPath: ['pokemon', 'evolutions'] },
+    },
+    {
+      name: 'first',
+      kind: 'Argument' as const,
+      position: { start: 120, end: 125, line: 6, column: 20 },
+      parentType: 'Pokemon',
+      schemaPath: ['Pokemon', 'abilities', 'first'],
+      context: { selectionPath: ['pokemon', 'abilities'] },
+    },
+  ]
+
+  console.log('📋 Identifier Resolutions:\n')
+
+  for (const identifier of testIdentifiers) {
+    const resolution = resolver.resolveIdentifier(identifier)
+    if (!resolution) continue
+
+    console.log(`🏷️  ${identifier.kind}: ${identifier.name}`)
+    console.log(`   ✅ Exists: ${resolution.exists}`)
+    console.log(`   🔗 URL: ${resolution.referenceUrl}`)
+
+    if (resolution.documentation) {
+      console.log(`   📝 Type: ${resolution.documentation.typeInfo}`)
+      if (resolution.documentation.description) {
+        console.log(`   💬 Description: ${resolution.documentation.description}`)
+      }
+      if (resolution.documentation.defaultValue) {
+        console.log(`   🎯 Default: ${resolution.documentation.defaultValue}`)
+      }
+    }
+
+    if (resolution.deprecated) {
+      console.log(`   ⚠️  DEPRECATED: ${resolution.deprecated.reason}`)
+    }
+
+    console.log()
+  }
+}
+
+/**
+ * Demonstrate full schema-aware analysis
+ */
+export const demonstrateSchemaAwareAnalysis = () => {
+  console.log('🔍 Schema-Aware Analysis\n')
+
+  const result = analyzeWithSchema(exampleQuery, pokemonSchema)
+
+  console.log(`📊 Analysis Summary:`)
+  console.log(`   • Valid GraphQL: ${result.analysis.isValid}`)
+  console.log(`   • Total identifiers: ${result.analysis.identifiers.all.length}`)
+  console.log(`   • Schema resolutions: ${result.resolutions.size}`)
+  console.log(`   • Schema errors: ${result.schemaErrors.length}\n`)
+
+  // Show validation errors
+  if (result.schemaErrors.length > 0) {
+    console.log('🚨 Schema Validation Issues:\n')
+    for (const error of result.schemaErrors) {
+      const emoji = error.severity === 'error' ? '❌' : '⚠️'
+      const pos = `${error.identifier.position.line}:${error.identifier.position.column}`
+      console.log(`   ${emoji} ${error.message} @ ${pos}`)
+    }
+    console.log()
+  }
+
+  // Show successful resolutions with hyperlink potential
+  console.log('🔗 Generated Hyperlinks:\n')
+  let linkCount = 0
+
+  for (const [key, resolution] of result.resolutions) {
+    if (resolution.exists && linkCount < 8) { // Show first 8 successful resolutions
+      const identifier = result.analysis.identifiers.all.find(id =>
+        key.startsWith(`${id.position.start}-${id.name}-${id.kind}`)
+      )
+
+      if (identifier) {
+        const pos = `${identifier.position.line}:${identifier.position.column}`
+        console.log(`   📍 ${identifier.name} (${identifier.kind}) → ${resolution.referenceUrl}`)
+
+        if (resolution.documentation?.description) {
+          const shortDesc = resolution.documentation.description.length > 50
+            ? resolution.documentation.description.substring(0, 50) + '...'
+            : resolution.documentation.description
+          console.log(`      💬 "${shortDesc}"`)
+        }
+
+        linkCount++
+      }
+    }
+  }
+}
+
+/**
+ * Demonstrate tooltip data extraction
+ */
+export const demonstrateTooltipData = () => {
+  console.log('\n💬 Tooltip Data Extraction\n')
+
+  const resolver = createPolenSchemaResolver(pokemonSchema)
+
+  // Simulate tooltip hover scenarios
+  const tooltipExamples = [
+    ['Pokemon'],
+    ['Pokemon', 'name'],
+    ['Pokemon', 'abilities'],
+    ['Pokemon', 'abilities', 'first'],
+    ['Ability', 'isHidden'],
+  ]
+
+  for (const schemaPath of tooltipExamples) {
+    const docs = resolver.getDocumentation(schemaPath)
+    if (docs) {
+      const pathStr = schemaPath.join(' → ')
+      console.log(`🏷️  ${pathStr}`)
+      console.log(`   📋 Type: ${docs.typeInfo}`)
+
+      if (docs.description) {
+        console.log(`   💬 Description: ${docs.description}`)
+      }
+
+      if (docs.defaultValue) {
+        console.log(`   🎯 Default: ${docs.defaultValue}`)
+      }
+
+      if (docs.deprecated) {
+        console.log(`   ⚠️  DEPRECATED: ${docs.deprecated.reason}`)
+      }
+
+      console.log()
+    }
+  }
+}
+
+/**
+ * Demonstrate URL generation customization
+ */
+export const demonstrateCustomURLGeneration = () => {
+  console.log('🛠️  Custom URL Generation\n')
+
+  // Different resolver configurations
+  const configurations = [
+    { name: 'Default', config: {} },
+    { name: 'Custom Base Path', config: { basePath: '/docs/api' } },
+    { name: 'No Fragments', config: { includeFragments: false } },
+    { name: 'Custom + No Fragments', config: { basePath: '/schema', includeFragments: false } },
+  ]
+
+  const testPaths = [
+    ['Pokemon'],
+    ['Pokemon', 'name'],
+    ['Pokemon', 'abilities', 'first'],
+  ]
+
+  for (const { name, config } of configurations) {
+    console.log(`📋 ${name}:`)
+    const resolver = createPolenSchemaResolver(pokemonSchema, config)
+
+    for (const path of testPaths) {
+      const url = resolver.generateReferenceLink(path)
+      console.log(`   ${path.join(' → ')} → ${url}`)
+    }
+    console.log()
+  }
+}
+
+/**
+ * Show integration with Polen's reference system
+ */
+export const demonstratePolenIntegration = () => {
+  console.log('🏗️  Polen Integration Preview\n')
+
+  // This demonstrates how the schema integration connects with Polen's existing systems
+  const result = analyzeWithSchema(exampleQuery, pokemonSchema, {
+    basePath: '/reference', // Polen's reference page base
+    includeFragments: true, // Enable field anchors
+  })
+
+  console.log('🔄 How this integrates with Polen:\n')
+
+  console.log('1. 📋 Schema Loading:')
+  console.log("   • Uses PROJECT_DATA.schema from Polen's build system")
+  console.log('   • Leverages existing schema processing pipeline')
+  console.log()
+
+  console.log('2. 🔗 Reference Links:')
+  console.log("   • Generates URLs matching Polen's /reference/* structure")
+  console.log('   • Works with existing TypeIndex and sidebar system')
+  console.log()
+
+  console.log('3. 💬 Documentation:')
+  console.log('   • Extracts descriptions for hover tooltips')
+  console.log('   • Provides type signatures for context')
+  console.log('   • Detects deprecation warnings')
+  console.log()
+
+  console.log('4. ✅ Validation:')
+  console.log('   • Build-time validation against actual schema')
+  console.log('   • Catches typos and invalid references')
+  console.log('   • Reports deprecation usage')
+  console.log()
+
+  // Show some example integrations
+  const validFields = Array.from(result.resolutions.values())
+    .filter(r => r.exists)
+    .slice(0, 3)
+
+  if (validFields.length > 0) {
+    console.log('📋 Example Reference Links:')
+    for (const resolution of validFields) {
+      console.log(`   • ${resolution.referenceUrl}`)
+    }
+  }
+}
+
+// Run examples if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  demonstrateSchemaResolution()
+  demonstrateSchemaAwareAnalysis()
+  demonstrateTooltipData()
+  demonstrateCustomURLGeneration()
+  demonstratePolenIntegration()
+}