polen 0.10.0 → 0.11.0-next.10

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

@@ -1,488 +0,0 @@
-/**
- * Layer 2: Schema Integration
- *
- * Bridge between GraphQL analysis and Polen's schema system.
- * Resolves identifiers against the actual schema, extracts documentation,
- * and generates reference URLs for navigation.
- */
-
-import {
-  getNamedType,
-  type GraphQLField,
-  type GraphQLInputField,
-  type GraphQLSchema,
-  type GraphQLType,
-  isInputObjectType,
-  isInterfaceType,
-  isListType,
-  isNonNullType,
-  isObjectType,
-} from 'graphql'
-import { analyze } from './analysis.js'
-import type { Identifier } from './types.js'
-
-/**
- * Documentation extracted from GraphQL schema
- */
-export interface Documentation {
-  /** Description from schema SDL or introspection */
-  description?: string
-  /** Type signature (e.g., "String!", "[User!]!") */
-  typeInfo: string
-  /** Whether this field/type is deprecated */
-  deprecated?: {
-    reason: string
-    replacement?: string
-  }
-  /** Default value for arguments */
-  defaultValue?: string
-}
-
-/**
- * Result of resolving an identifier against the schema
- */
-export interface SchemaResolution {
-  /** Whether the identifier exists in the schema */
-  exists: boolean
-  /** Documentation extracted from schema */
-  documentation?: Documentation
-  /** URL to the reference page for this identifier */
-  referenceUrl: string
-  /** Whether this identifier is deprecated */
-  deprecated?: {
-    reason: string
-    replacement?: string
-  }
-  /** The GraphQL type if this is a type identifier */
-  graphqlType?: GraphQLType
-}
-
-/**
- * Interface for resolving GraphQL identifiers against a schema
- */
-export interface SchemaResolver {
-  /**
-   * Resolve an identifier against the schema
-   */
-  resolveIdentifier(identifier: Identifier): SchemaResolution | null
-
-  /**
-   * Get documentation for a schema path
-   */
-  getDocumentation(schemaPath: string[]): Documentation | null
-
-  /**
-   * Generate a reference URL for a schema path
-   */
-  generateReferenceLink(schemaPath: string[]): string
-
-  /**
-   * Check if a type exists in the schema
-   */
-  typeExists(typeName: string): boolean
-
-  /**
-   * Get all available types for validation
-   */
-  getAllTypes(): string[]
-}
-
-/**
- * Configuration for URL generation
- */
-export interface RouteConfig {
-  /** Base path for reference pages (default: "/reference") */
-  basePath?: string
-  /** Whether to include fragments in URLs (default: true) */
-  includeFragments?: boolean
-}
-
-/**
- * Polen's implementation of SchemaResolver
- */
-export class PolenSchemaResolver implements SchemaResolver {
-  constructor(
-    private schema: GraphQLSchema,
-    private routeConfig: RouteConfig = {},
-  ) {}
-
-  /**
-   * Resolve an identifier against the schema
-   */
-  resolveIdentifier(identifier: Identifier): SchemaResolution | null {
-    const basePath = this.routeConfig.basePath || `/reference`
-
-    switch (identifier.kind) {
-      case `Type`:
-        return this.resolveType(identifier, basePath)
-
-      case `Field`:
-        return this.resolveField(identifier, basePath)
-
-      case `Argument`:
-        return this.resolveArgument(identifier, basePath)
-
-      case `Variable`:
-        // Variables don't have schema resolution
-        return {
-          exists: true,
-          referenceUrl: `${basePath}#variables`,
-          documentation: {
-            typeInfo: `Variable`,
-            description: `Query variable: $${identifier.name}`,
-          },
-        }
-
-      case `Directive`:
-        return this.resolveDirective(identifier, basePath)
-
-      case `Fragment`:
-        // Fragments don't have schema resolution
-        return {
-          exists: true,
-          referenceUrl: `${basePath}#fragments`,
-          documentation: {
-            typeInfo: `Fragment`,
-            description: `Fragment: ${identifier.name}`,
-          },
-        }
-
-      default:
-        return null
-    }
-  }
-
-  /**
-   * Get documentation for a schema path
-   */
-  getDocumentation(schemaPath: string[]): Documentation | null {
-    if (schemaPath.length === 0) return null
-
-    const [typeName, fieldName, argName] = schemaPath
-
-    if (!typeName) return null
-
-    const type = this.schema.getType(typeName)
-    if (!type) return null
-
-    // Type-level documentation
-    if (schemaPath.length === 1) {
-      return {
-        typeInfo: this.getTypeSignature(type),
-        description: type.description || undefined,
-        deprecated: `deprecationReason` in type
-          ? {
-            reason: (type as any).deprecationReason,
-          }
-          : undefined,
-      }
-    }
-
-    // Field-level documentation
-    if (fieldName && schemaPath.length === 2) {
-      const field = this.getFieldFromType(type, fieldName)
-      if (!field) return null
-
-      return {
-        typeInfo: this.getTypeSignature(field.type),
-        description: field.description || undefined,
-        deprecated: field.deprecationReason
-          ? {
-            reason: field.deprecationReason,
-          }
-          : undefined,
-      }
-    }
-
-    // Argument-level documentation
-    if (fieldName && argName && schemaPath.length === 3) {
-      const field = this.getFieldFromType(type, fieldName)
-      if (!field || !(`args` in field)) return null
-
-      const arg = field.args.find((a: any) => a.name === argName)
-      if (!arg) return null
-
-      return {
-        typeInfo: this.getTypeSignature(arg.type),
-        description: arg.description || undefined,
-        defaultValue: arg.defaultValue !== undefined
-          ? String(arg.defaultValue)
-          : undefined,
-      }
-    }
-
-    return null
-  }
-
-  /**
-   * Generate a reference URL for a schema path
-   */
-  generateReferenceLink(schemaPath: string[]): string {
-    const basePath = this.routeConfig.basePath || `/reference`
-    const includeFragments = this.routeConfig.includeFragments !== false
-
-    if (schemaPath.length === 0) return basePath
-
-    const [typeName, fieldName, argName] = schemaPath
-
-    // Type reference
-    if (schemaPath.length === 1) {
-      return `${basePath}/${typeName}`
-    }
-
-    // Field reference
-    if (fieldName && schemaPath.length === 2) {
-      const fragment = includeFragments ? `#${fieldName}` : ``
-      return `${basePath}/${typeName}${fragment}`
-    }
-
-    // Argument reference
-    if (fieldName && argName && schemaPath.length === 3) {
-      const fragment = includeFragments ? `#${fieldName}-${argName}` : ``
-      return `${basePath}/${typeName}${fragment}`
-    }
-
-    return `${basePath}/${typeName}`
-  }
-
-  /**
-   * Check if a type exists in the schema
-   */
-  typeExists(typeName: string): boolean {
-    return !!this.schema.getType(typeName)
-  }
-
-  /**
-   * Get all available types for validation
-   */
-  getAllTypes(): string[] {
-    return Object.keys(this.schema.getTypeMap())
-      .filter(name => !name.startsWith(`__`)) // Filter out introspection types
-  }
-
-  // Private helper methods
-
-  private resolveType(identifier: Identifier, basePath: string): SchemaResolution {
-    const type = this.schema.getType(identifier.name)
-
-    return {
-      exists: !!type,
-      graphqlType: type || undefined,
-      referenceUrl: `${basePath}/${identifier.name}`,
-      documentation: type
-        ? {
-          typeInfo: this.getTypeSignature(type),
-          description: type.description || undefined,
-        }
-        : undefined,
-    }
-  }
-
-  private resolveField(identifier: Identifier, basePath: string): SchemaResolution {
-    if (!identifier.parentType) {
-      return {
-        exists: false,
-        referenceUrl: `${basePath}#${identifier.name}`,
-      }
-    }
-
-    const parentType = this.schema.getType(identifier.parentType)
-    if (!parentType) {
-      return {
-        exists: false,
-        referenceUrl: `${basePath}/${identifier.parentType}#${identifier.name}`,
-      }
-    }
-
-    const field = this.getFieldFromType(parentType, identifier.name)
-
-    return {
-      exists: !!field,
-      referenceUrl: `${basePath}/${identifier.parentType}#${identifier.name}`,
-      documentation: field
-        ? {
-          typeInfo: this.getTypeSignature(field.type),
-          description: field.description || undefined,
-          deprecated: field.deprecationReason
-            ? {
-              reason: field.deprecationReason,
-            }
-            : undefined,
-        }
-        : undefined,
-      deprecated: field?.deprecationReason
-        ? {
-          reason: field.deprecationReason,
-        }
-        : undefined,
-    }
-  }
-
-  private resolveArgument(identifier: Identifier, basePath: string): SchemaResolution {
-    const schemaPath = identifier.schemaPath
-    if (schemaPath.length < 3) {
-      return {
-        exists: false,
-        referenceUrl: `${basePath}#${identifier.name}`,
-      }
-    }
-
-    const [typeName, fieldName] = schemaPath
-    if (!typeName || !fieldName) {
-      return {
-        exists: false,
-        referenceUrl: `${basePath}#${identifier.name}`,
-      }
-    }
-
-    const parentType = this.schema.getType(typeName)
-    if (!parentType) {
-      return {
-        exists: false,
-        referenceUrl: `${basePath}/${typeName}#${fieldName}-${identifier.name}`,
-      }
-    }
-
-    const field = this.getFieldFromType(parentType, fieldName)
-    if (!field || !(`args` in field)) {
-      return {
-        exists: false,
-        referenceUrl: `${basePath}/${typeName}#${fieldName}-${identifier.name}`,
-      }
-    }
-
-    const arg = field.args.find((a: any) => a.name === identifier.name)
-
-    return {
-      exists: !!arg,
-      referenceUrl: `${basePath}/${typeName}#${fieldName}-${identifier.name}`,
-      documentation: arg
-        ? {
-          typeInfo: this.getTypeSignature(arg.type),
-          description: arg.description || undefined,
-          defaultValue: arg.defaultValue !== undefined
-            ? String(arg.defaultValue)
-            : undefined,
-        }
-        : undefined,
-    }
-  }
-
-  private resolveDirective(identifier: Identifier, basePath: string): SchemaResolution {
-    const directive = this.schema.getDirective(identifier.name)
-
-    return {
-      exists: !!directive,
-      referenceUrl: `${basePath}/directives#${identifier.name}`,
-      documentation: directive
-        ? {
-          typeInfo: `Directive`,
-          description: directive.description || undefined,
-        }
-        : undefined,
-    }
-  }
-
-  private getFieldFromType(type: GraphQLType, fieldName: string): GraphQLField<any, any> | GraphQLInputField | null {
-    if (isObjectType(type) || isInterfaceType(type)) {
-      return type.getFields()[fieldName] || null
-    }
-
-    if (isInputObjectType(type)) {
-      return type.getFields()[fieldName] || null
-    }
-
-    return null
-  }
-
-  private getTypeSignature(type: GraphQLType): string {
-    if (isNonNullType(type)) {
-      return `${this.getTypeSignature(type.ofType)}!`
-    }
-
-    if (isListType(type)) {
-      return `[${this.getTypeSignature(type.ofType)}]`
-    }
-
-    return getNamedType(type).name
-  }
-}
-
-/**
- * Create a schema resolver for Polen
- */
-export const createPolenSchemaResolver = (
-  schema: GraphQLSchema,
-  routeConfig?: RouteConfig,
-): SchemaResolver => {
-  return new PolenSchemaResolver(schema, routeConfig)
-}
-
-/**
- * Enhanced analysis result with schema resolution
- */
-export interface SchemaAwareAnalysisResult {
-  /** Original analysis result */
-  analysis: import('./types.js').AnalysisResult
-  /** Schema resolutions for all identifiers */
-  resolutions: Map<string, SchemaResolution>
-  /** Validation errors from schema checking */
-  schemaErrors: {
-    identifier: Identifier
-    message: string
-    severity: `error` | `warning`
-  }[]
-}
-
-/**
- * Perform schema-aware analysis of a GraphQL document
- */
-export const analyzeWithSchema = (
-  source: string,
-  schema: GraphQLSchema,
-  routeConfig?: RouteConfig,
-): SchemaAwareAnalysisResult => {
-  const analysis = analyze(source, {
-    schema,
-    validateAgainstSchema: true,
-    includePositions: true,
-  })
-
-  const resolver = createPolenSchemaResolver(schema, routeConfig)
-  const resolutions = new Map<string, SchemaResolution>()
-  const schemaErrors: SchemaAwareAnalysisResult[`schemaErrors`] = []
-
-  // Resolve all identifiers against schema
-  for (const identifier of analysis.identifiers.all) {
-    const key = `${identifier.position.start}-${identifier.name}-${identifier.kind}`
-    const resolution = resolver.resolveIdentifier(identifier)
-
-    if (resolution) {
-      resolutions.set(key, resolution)
-
-      // Add validation errors for non-existent identifiers
-      if (!resolution.exists && (identifier.kind === `Type` || identifier.kind === `Field`)) {
-        schemaErrors.push({
-          identifier,
-          message: `${identifier.kind} "${identifier.name}" does not exist in schema`,
-          severity: `error`,
-        })
-      }
-
-      // Add deprecation warnings
-      if (resolution.deprecated) {
-        schemaErrors.push({
-          identifier,
-          message: `${identifier.kind} "${identifier.name}" is deprecated: ${resolution.deprecated.reason}`,
-          severity: `warning`,
-        })
-      }
-    }
-  }
-
-  return {
-    analysis,
-    resolutions,
-    schemaErrors,
-  }
-}

package/src/lib/graphql-document/types.ts

@@ -1,129 +0,0 @@
-import type { DocumentNode, GraphQLError, GraphQLSchema } from 'graphql'
-
-/**
- * Represents a GraphQL identifier found in a document
- */
-export interface Identifier {
-  /** The name of the identifier (e.g., 'User', 'name', 'id') */
-  name: string
-  /** The kind of GraphQL construct this identifier represents */
-  kind: `Type` | `Field` | `Argument` | `Directive` | `Variable` | `Fragment`
-  /** Position information in the source document */
-  position: {
-    /** Character offset from start of document */
-    start: number
-    /** Character offset for end of identifier */
-    end: number
-    /** Line number (1-based) */
-    line: number
-    /** Column number (1-based) */
-    column: number
-  }
-  /** The parent type name if this is a field or argument */
-  parentType?: string
-  /** Path through the schema to this identifier (e.g., ['User', 'posts', 'title']) */
-  schemaPath: string[]
-  /** Context about where this identifier appears */
-  context: IdentifierContext
-}
-
-/**
- * Additional context about where an identifier appears in the document
- */
-export interface IdentifierContext {
-  /** The operation type if this identifier is within an operation */
-  operationType?: `query` | `mutation` | `subscription`
-  /** The operation name if this identifier is within a named operation */
-  operationName?: string
-  /** Whether this identifier is in a fragment definition */
-  inFragment?: string
-  /** The selection path leading to this identifier */
-  selectionPath: string[]
-}
-
-/**
- * Map of all identifiers found in a GraphQL document
- */
-export interface IdentifierMap {
-  /** Quick lookup by character position */
-  byPosition: Map<number, Identifier>
-  /** Grouped by identifier kind for easy filtering */
-  byKind: Map<Identifier[`kind`], Identifier[]>
-  /** Any validation errors found during analysis */
-  errors: AnalysisError[]
-  /** All identifiers as a flat array */
-  all: Identifier[]
-}
-
-/**
- * Analysis error with context about the identifier that caused it
- */
-export interface AnalysisError {
-  /** The identifier that caused the error (if applicable) */
-  identifier?: Identifier
-  /** Human-readable error message */
-  message: string
-  /** Error severity level */
-  severity: `error` | `warning` | `info`
-  /** Position in the document where the error occurred */
-  position?: {
-    line: number
-    column: number
-  }
-}
-
-/**
- * Result of analyzing a GraphQL document
- */
-export interface AnalysisResult {
-  /** The parsed AST */
-  ast: DocumentNode
-  /** Map of all identifiers found */
-  identifiers: IdentifierMap
-  /** Whether the document parsed successfully */
-  isValid: boolean
-  /** Any parse or validation errors */
-  errors: GraphQLError[]
-}
-
-/**
- * Configuration for GraphQL document analysis
- */
-export interface AnalysisConfig {
-  /** Whether to include position information for identifiers */
-  includePositions?: boolean
-  /** Whether to validate against a schema (if provided) */
-  validateAgainstSchema?: boolean
-  /** Schema to validate against */
-  schema?: GraphQLSchema
-  /** Whether to extract fragment information */
-  includeFragments?: boolean
-}
-
-/**
- * Interface for the main GraphQL analyzer
- */
-export interface GraphQLAnalyzer {
-  /**
-   * Parse a GraphQL document string into an AST
-   */
-  parse(source: string): DocumentNode
-
-  /**
-   * Extract all identifiers from a GraphQL AST
-   */
-  extractIdentifiers(ast: DocumentNode, config?: AnalysisConfig): IdentifierMap
-
-  /**
-   * Validate a GraphQL document against a schema
-   */
-  validateAgainstSchema(
-    ast: DocumentNode,
-    schema: GraphQLSchema,
-  ): GraphQLError[]
-
-  /**
-   * Perform complete analysis of a GraphQL document
-   */
-  analyze(source: string, config?: AnalysisConfig): AnalysisResult
-}

package/src/template/components/CodeHikePre.tsx

@@ -1,51 +0,0 @@
-import { Pre as CodeHikePre } from 'codehike/code'
-import React from 'react'
-import { GraphQLDocument } from '../../lib/graphql-document/components/GraphQLDocument.js'
-
-type CodeHikePreProps = React.ComponentProps<typeof CodeHikePre>
-type HTMLPreProps = React.ComponentPropsWithoutRef<'pre'>
-type PreProps = CodeHikePreProps | HTMLPreProps
-
-/**
- * Custom Pre component that adds interactive GraphQL support to Code Hike
- *
- * Usage in MDX:
- * ```graphql interactive
- * query { ... }
- * ```
- */
-export const Pre: React.FC<PreProps> = (props) => {
-  // Check if this is a Code Hike pre component (has 'code' prop)
-  if ('code' in props && props.code) {
-    const { code } = props
-
-    // Check if this is an interactive GraphQL block
-    if (code.lang === 'graphql' && code.meta?.includes('interactive')) {
-      // Extract the GraphQL schema if available
-      const schema = typeof window !== 'undefined'
-        ? (window as any).__POLEN_GRAPHQL_SCHEMA__
-        : null
-
-      // For interactive GraphQL blocks, we need to apply Code Hike's styling
-      // but add GraphQLDocument's interactive features
-      return (
-        <GraphQLDocument
-          schema={schema}
-          options={{
-            className: 'ch-code-container',
-            // Use Code Hike's Pre component for rendering
-            renderCode: () => <CodeHikePre {...props as CodeHikePreProps} />,
-          }}
-        >
-          {code.code}
-        </GraphQLDocument>
-      )
-    }
-
-    // For other Code Hike code blocks, use Code Hike's Pre
-    return <CodeHikePre {...props as CodeHikePreProps} />
-  }
-
-  // For standard HTML pre elements, render as-is
-  return <pre {...props as HTMLPreProps} />
-}

package/src/template/routes/reference.$type.$field.tsx

@@ -1,34 +0,0 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { ReactRouterAid } from '#lib/react-router-aid/index'
-import { useLoaderData } from '#lib/react-router-loader/react-router-loader'
-import { useParams } from 'react-router'
-import { Field } from '../components/Field.js'
-import { MissingSchema } from '../components/MissingSchema.js'
-import type { reference } from './reference.js'
-
-const Component = () => {
-  const params = useParams() as { type: string; field: string }
-  const data = useLoaderData<typeof reference.loader>(`reference`)
-  if (!data.schema) {
-    return <MissingSchema />
-  }
-
-  const type = data.schema.getType(params.type)
-  if (!type) return `Could not find type ${params.type}`
-  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
-    return `Type ${params.type} does not have fields`
-  }
-
-  const fields = type.getFields()
-  const field = fields[params.field]
-  if (!field) {
-    return `Could not find field ${params.field} on type ${params.type}`
-  }
-
-  return <Field data={field} />
-}
-
-export const reference$type$field = ReactRouterAid.createRoute({
-  path: `:type/:field`,
-  Component,
-})