polen 0.10.0-next.14 → 0.10.0-next.3

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

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

@@ -1,365 +0,0 @@
-import { buildSchema } from 'graphql'
-import { describe, expect, it } from 'vitest'
-import { analyzeWithSchema, createPolenSchemaResolver } from './schema-integration.ts'
-
-// Test schema
-const testSchema = buildSchema(`
-  """
-  A user in the system
-  """
-  type User {
-    """
-    The user's unique identifier
-    """
-    id: ID!
-    
-    """
-    The user's full name
-    """
-    name: String!
-    
-    """
-    The user's email address
-    """
-    email: String!
-    
-    """
-    User's posts
-    """
-    posts(
-      """
-      Maximum number of posts to return
-      """
-      first: Int = 10
-      
-      """
-      Filter posts after this cursor
-      """
-      after: String
-    ): [Post!]!
-    
-    """
-    @deprecated Use profile.avatar instead
-    """
-    avatar: String @deprecated(reason: "Use profile.avatar instead")
-  }
-
-  """
-  A blog post
-  """
-  type Post {
-    id: ID!
-    title: String!
-    content: String!
-    author: User!
-  }
-
-  """
-  Input for creating a user
-  """
-  input CreateUserInput {
-    name: String!
-    email: String!
-  }
-
-  type Query {
-    """
-    Get a user by ID
-    """
-    user(id: ID!): User
-    
-    """
-    Search for users
-    """
-    users(query: String!): [User!]!
-  }
-
-  type Mutation {
-    """
-    Create a new user
-    """
-    createUser(input: CreateUserInput!): User!
-  }
-
-  """
-  Custom directive for validation
-  """
-  directive @validate(pattern: String!) on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
-`)
-
-describe('Schema Integration', () => {
-  describe('PolenSchemaResolver', () => {
-    const resolver = createPolenSchemaResolver(testSchema)
-
-    describe('Type Resolution', () => {
-      it('should resolve existing types', () => {
-        const identifier = {
-          name: 'User',
-          kind: 'Type' as const,
-          position: { start: 0, end: 4, line: 1, column: 1 },
-          schemaPath: ['User'],
-          context: { selectionPath: [] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(true)
-        expect(resolution!.referenceUrl).toBe('/reference/User')
-        expect(resolution!.documentation?.description).toContain('A user in the system')
-        expect(resolution!.documentation?.typeInfo).toBe('User')
-      })
-
-      it('should handle non-existent types', () => {
-        const identifier = {
-          name: 'NonExistentType',
-          kind: 'Type' as const,
-          position: { start: 0, end: 15, line: 1, column: 1 },
-          schemaPath: ['NonExistentType'],
-          context: { selectionPath: [] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(false)
-        expect(resolution!.referenceUrl).toBe('/reference/NonExistentType')
-        expect(resolution!.documentation).toBeUndefined()
-      })
-    })
-
-    describe('Field Resolution', () => {
-      it('should resolve existing fields', () => {
-        const identifier = {
-          name: 'name',
-          kind: 'Field' as const,
-          position: { start: 0, end: 4, line: 1, column: 1 },
-          parentType: 'User',
-          schemaPath: ['User', 'name'],
-          context: { selectionPath: ['name'] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(true)
-        expect(resolution!.referenceUrl).toBe('/reference/User#name')
-        expect(resolution!.documentation?.description).toContain("The user's full name")
-        expect(resolution!.documentation?.typeInfo).toBe('String!')
-      })
-
-      it('should detect deprecated fields', () => {
-        const identifier = {
-          name: 'avatar',
-          kind: 'Field' as const,
-          position: { start: 0, end: 6, line: 1, column: 1 },
-          parentType: 'User',
-          schemaPath: ['User', 'avatar'],
-          context: { selectionPath: ['avatar'] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(true)
-        expect(resolution!.deprecated).toBeDefined()
-        expect(resolution!.deprecated!.reason).toBe('Use profile.avatar instead')
-      })
-
-      it('should handle non-existent fields', () => {
-        const identifier = {
-          name: 'nonExistentField',
-          kind: 'Field' as const,
-          position: { start: 0, end: 16, line: 1, column: 1 },
-          parentType: 'User',
-          schemaPath: ['User', 'nonExistentField'],
-          context: { selectionPath: ['nonExistentField'] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(false)
-        expect(resolution!.referenceUrl).toBe('/reference/User#nonExistentField')
-      })
-    })
-
-    describe('Argument Resolution', () => {
-      it('should resolve field arguments', () => {
-        const identifier = {
-          name: 'first',
-          kind: 'Argument' as const,
-          position: { start: 0, end: 5, line: 1, column: 1 },
-          parentType: 'User',
-          schemaPath: ['User', 'posts', 'first'],
-          context: { selectionPath: ['posts'] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(true)
-        expect(resolution!.referenceUrl).toBe('/reference/User#posts-first')
-        expect(resolution!.documentation?.description).toContain('Maximum number of posts')
-        expect(resolution!.documentation?.typeInfo).toBe('Int')
-        expect(resolution!.documentation?.defaultValue).toBe('10')
-      })
-    })
-
-    describe('Variable Resolution', () => {
-      it('should handle variables', () => {
-        const identifier = {
-          name: 'id',
-          kind: 'Variable' as const,
-          position: { start: 0, end: 2, line: 1, column: 1 },
-          schemaPath: ['id'],
-          context: { selectionPath: [] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(true)
-        expect(resolution!.referenceUrl).toBe('/reference#variables')
-        expect(resolution!.documentation?.typeInfo).toBe('Variable')
-        expect(resolution!.documentation?.description).toBe('Query variable: $id')
-      })
-    })
-
-    describe('Directive Resolution', () => {
-      it('should resolve directives', () => {
-        const identifier = {
-          name: 'validate',
-          kind: 'Directive' as const,
-          position: { start: 0, end: 8, line: 1, column: 1 },
-          schemaPath: ['validate'],
-          context: { selectionPath: [] },
-        }
-
-        const resolution = resolver.resolveIdentifier(identifier)
-
-        expect(resolution).toBeDefined()
-        expect(resolution!.exists).toBe(true)
-        expect(resolution!.referenceUrl).toBe('/reference/directives#validate')
-        expect(resolution!.documentation?.description).toContain('Custom directive for validation')
-      })
-    })
-
-    describe('URL Generation', () => {
-      it('should generate correct URLs with custom base path', () => {
-        const customResolver = createPolenSchemaResolver(testSchema, {
-          basePath: '/docs/schema',
-        })
-
-        expect(customResolver.generateReferenceLink(['User'])).toBe('/docs/schema/User')
-        expect(customResolver.generateReferenceLink(['User', 'name'])).toBe('/docs/schema/User#name')
-        expect(customResolver.generateReferenceLink(['User', 'posts', 'first'])).toBe('/docs/schema/User#posts-first')
-      })
-
-      it('should handle fragment configuration', () => {
-        const noFragmentResolver = createPolenSchemaResolver(testSchema, {
-          includeFragments: false,
-        })
-
-        expect(noFragmentResolver.generateReferenceLink(['User', 'name'])).toBe('/reference/User')
-      })
-    })
-
-    describe('Documentation Extraction', () => {
-      it('should extract type documentation', () => {
-        const docs = resolver.getDocumentation(['User'])
-
-        expect(docs).toBeDefined()
-        expect(docs!.description).toContain('A user in the system')
-        expect(docs!.typeInfo).toBe('User')
-      })
-
-      it('should extract field documentation', () => {
-        const docs = resolver.getDocumentation(['User', 'email'])
-
-        expect(docs).toBeDefined()
-        expect(docs!.description).toContain("The user's email address")
-        expect(docs!.typeInfo).toBe('String!')
-      })
-
-      it('should extract argument documentation', () => {
-        const docs = resolver.getDocumentation(['User', 'posts', 'after'])
-
-        expect(docs).toBeDefined()
-        expect(docs!.description).toContain('Filter posts after this cursor')
-        expect(docs!.typeInfo).toBe('String')
-      })
-    })
-
-    describe('Schema Validation', () => {
-      it('should return all types', () => {
-        const types = resolver.getAllTypes()
-
-        expect(types).toContain('User')
-        expect(types).toContain('Post')
-        expect(types).toContain('CreateUserInput')
-        expect(types).toContain('Query')
-        expect(types).toContain('Mutation')
-        expect(types).not.toContain('__Schema') // Should filter introspection types
-      })
-
-      it('should check type existence', () => {
-        expect(resolver.typeExists('User')).toBe(true)
-        expect(resolver.typeExists('NonExistentType')).toBe(false)
-      })
-    })
-  })
-
-  describe('Schema-Aware Analysis', () => {
-    it('should perform complete schema-aware analysis', () => {
-      const source = `
-        query GetUser($id: ID!) {
-          user(id: $id) {
-            name
-            email
-            avatar
-          }
-        }
-      `
-
-      const result = analyzeWithSchema(source, testSchema)
-
-      expect(result.analysis.isValid).toBe(true)
-      expect(result.resolutions.size).toBeGreaterThan(0)
-      expect(result.schemaErrors.length).toBeGreaterThan(0)
-
-      // Should have deprecation warning for avatar field
-      const deprecationWarning = result.schemaErrors.find(
-        error => error.message.includes('avatar') && error.message.includes('deprecated'),
-      )
-      expect(deprecationWarning).toBeDefined()
-      expect(deprecationWarning!.severity).toBe('warning')
-    })
-
-    it('should resolve identifiers correctly', () => {
-      const source = `
-        query {
-          user(id: "123") {
-            name
-          }
-        }
-      `
-
-      const result = analyzeWithSchema(source, testSchema)
-
-      // Find the name field resolution
-      const nameField = result.analysis.identifiers.all.find(
-        id => id.name === 'name' && id.kind === 'Field',
-      )
-      expect(nameField).toBeDefined()
-
-      const nameResolutionKey = `${nameField!.position.start}-${nameField!.name}-${nameField!.kind}`
-      const nameResolution = result.resolutions.get(nameResolutionKey)
-
-      expect(nameResolution).toBeDefined()
-      expect(nameResolution!.exists).toBe(true)
-      expect(nameResolution!.referenceUrl).toBe('/reference/User#name')
-      expect(nameResolution!.documentation?.typeInfo).toBe('String!')
-    })
-  })
-})