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

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

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

@@ -0,0 +1,365 @@
+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!')
+    })
+  })
+})