polen 0.10.0-next.13 → 0.10.0-next.3

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

@@ -1,271 +0,0 @@
-/**
- * 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

@@ -1,20 +0,0 @@
-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

@@ -1,341 +0,0 @@
-/**
- * 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()
-}