polen/src/template/components/GraphQLInteractive/lib/parser.ts

A framework for delightful GraphQL developer portals

/**
 * Tree-sitter GraphQL parsing with semantic analysis
 *
 * This module combines tree-sitter syntax parsing with GraphQL semantic
 * analysis to create unified tokens for interactive code blocks.
 */

import type { CodeAnnotation } from 'codehike/code'
import {
  getNamedType,
  type GraphQLArgument,
  GraphQLEnumType,
  type GraphQLField,
  GraphQLInputObjectType,
  GraphQLInterfaceType,
  GraphQLObjectType,
  type GraphQLOutputType,
  GraphQLScalarType,
  type GraphQLSchema,
  GraphQLUnionType,
  isInterfaceType,
  isObjectType,
} from 'graphql'
import graphqlWasmUrl from 'tree-sitter-graphql-grammar-wasm/grammar.wasm?url'
import * as WebTreeSitter from 'web-tree-sitter'
import treeSitterWasmUrl from 'web-tree-sitter/tree-sitter.wasm?url'
import {
  isKeywordNodeType,
  isLiteralNodeType,
  isPunctuationNodeType,
  type TreeSitterGraphQLNodeType,
} from './graphql-node-types.js'
import type { SemanticNode } from './semantic-nodes.js'
import {
  isArgument,
  isFragment,
  isInputField,
  isInvalidField,
  isOperation,
  isOutputField,
  isVariable,
} from './semantic-nodes.js'

/**
 * Unified token structure that combines tree-sitter and GraphQL semantics
 *
 * This interface represents a single parsed token from a GraphQL document,
 * enriched with semantic information from the GraphQL schema when available.
 * It provides a consistent API for accessing syntax highlighting, interactivity,
 * and CodeHike annotation data.
 *
 * @example
 * ```typescript
 * const tokens = await parseGraphQLWithTreeSitter(code, [], schema)
 * const fieldToken = tokens.find(t => t.text === 'name')
 *
 * if (fieldToken?.polen.isInteractive()) {
 *   const url = fieldToken.polen.getReferenceUrl()
 *   console.log(`Navigate to: ${url}`)
 * }
 * ```
 */
export interface GraphQLToken {
  /** Reference to the tree-sitter node that this token represents */
  treeSitterNode: WebTreeSitter.Node

  /**
   * Optional semantic information from GraphQL schema analysis
   * This includes type information, field definitions, and validation results
   */
  semantic?: SemanticNode

  /** Text content of the token (computed from tree-sitter node) */
  get text(): string

  /** Start character position in the source code (computed from tree-sitter node) */
  get start(): number

  /** End character position in the source code (computed from tree-sitter node) */
  get end(): number

  /** Polen specific functionality for interactive GraphQL documentation */
  polen: {
    /** Check if this token should be interactive (clickable/hoverable) */
    isInteractive: () => boolean
    /** Get the reference URL for navigation, or null if not applicable */
    getReferenceUrl: () => string | null
  }

  /** Syntax highlighting functionality */
  highlighter: {
    /** Get the CSS class name for styling this token */
    getCssClass: () => string
  }

  /** CodeHike integration for enhanced code block features */
  codeHike: {
    /** Array of CodeHike annotations that apply to this token */
    annotations: CodeAnnotation[]
  }
}

/**
 * Implementation of unified token
 */
class UnifiedToken implements GraphQLToken {
  public polen: { isInteractive: () => boolean; getReferenceUrl: () => string | null }
  public highlighter: { getCssClass: () => string }
  public codeHike: { annotations: CodeAnnotation[] }

  // Cache these values to avoid WASM access issues
  private _text: string
  private _start: number
  private _end: number
  private _nodeType: TreeSitterGraphQLNodeType

  constructor(
    public treeSitterNode: WebTreeSitter.Node,
    public semantic: SemanticNode | undefined,
    annotations: CodeAnnotation[],
  ) {
    // Cache the values immediately to avoid WASM access issues later
    // This works for both real WebTreeSitter nodes and synthetic nodes
    this._text = treeSitterNode.text
    this._start = treeSitterNode.startIndex
    this._end = treeSitterNode.endIndex
    this._nodeType = treeSitterNode.type as TreeSitterGraphQLNodeType

    this.codeHike = { annotations }

    // Polen namespace
    this.polen = {
      isInteractive: () => this._isInteractive(),
      getReferenceUrl: () => this._getReferenceUrl(),
    }

    // Highlighter namespace
    this.highlighter = {
      getCssClass: () => this._getCssClass(),
    }
  }

  get text(): string {
    return this._text
  }

  get start(): number {
    return this._start
  }

  get end(): number {
    return this._end
  }

  private _getCssClass(): string {
    const nodeType = this._nodeType

    // Development-only validation
    if (process.env['NODE_ENV'] === 'development') {
      // Validate that the node type is actually a valid TreeSitterGraphQLNodeType
      const validTypes = new Set([
        // Add a few common types for validation
        'document',
        'name',
        'field',
        'argument',
        'variable',
        'comment',
        'error_hint',
        'whitespace',
        'string_value',
        'int_value',
        'float_value',
        'query',
        'mutation',
        'subscription',
      ])

      if (!validTypes.has(nodeType as any) && !nodeType.match(/^[a-z_]+$/)) {
        console.warn(`Unknown tree-sitter node type: "${nodeType}". Consider adding to TreeSitterGraphQLNodeType.`)
      }
    }

    // Error hints
    if (nodeType === 'error_hint') {
      return 'graphql-error-hint'
    }

    // Comments
    if (nodeType === 'comment' || nodeType === 'description') {
      return 'graphql-comment'
    }

    // Keywords
    if (isKeywordNodeType(nodeType)) {
      return 'graphql-keyword'
    }

    // Literals
    if (nodeType === 'string_value') return 'graphql-string'
    if (nodeType === 'int_value' || nodeType === 'float_value') return 'graphql-number'

    // Punctuation
    if (isPunctuationNodeType(nodeType)) {
      return 'graphql-punctuation'
    }

    // Names - use semantic info for better classification
    if (nodeType === 'name') {
      // Check if this is an invalid field (has invalidField semantic)
      if (this.semantic && 'kind' in this.semantic && this.semantic.kind === 'InvalidField') {
        return 'graphql-field-error'
      }

      if (isOutputField(this.semantic) || isInputField(this.semantic)) {
        return 'graphql-field-interactive'
      }
      if (
        this.semantic instanceof GraphQLObjectType
        || this.semantic instanceof GraphQLScalarType
        || this.semantic instanceof GraphQLInterfaceType
      ) {
        return 'graphql-type-interactive'
      }
      if (isVariable(this.semantic)) {
        return 'graphql-variable'
      }
      if (isOperation(this.semantic)) {
        return 'graphql-operation'
      }
      if (isFragment(this.semantic)) {
        return 'graphql-fragment'
      }
      if (isArgument(this.semantic)) {
        return 'graphql-argument'
      }
    }

    // Variables
    if (nodeType === 'variable') return 'graphql-variable'

    return 'graphql-text'
  }

  private _isInteractive(): boolean {
    if (!this.semantic) return false

    // Fields, type references, arguments, and invalid fields are interactive
    return isOutputField(this.semantic)
      || isInputField(this.semantic)
      || isArgument(this.semantic)
      || isInvalidField(this.semantic) // Invalid fields should show error popovers
      || this.semantic instanceof GraphQLObjectType
      || this.semantic instanceof GraphQLScalarType
      || this.semantic instanceof GraphQLInterfaceType
      || this.semantic instanceof GraphQLUnionType
      || this.semantic instanceof GraphQLEnumType
      || this.semantic instanceof GraphQLInputObjectType
  }

  private _getReferenceUrl(): string | null {
    if (!this.semantic) return null

    // Arguments - use #<field>__<argument> pattern
    if (isArgument(this.semantic)) {
      return `/reference/${this.semantic.parentType.name}#${this.semantic.parentField.name}__${this.semantic.argumentDef.name}`
    }

    // Output fields - use hash links since field routes aren't connected yet
    if (isOutputField(this.semantic)) {
      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
    }

    // Input fields - use hash links since field routes aren't connected yet
    if (isInputField(this.semantic)) {
      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
    }

    // Type references - use :type pattern
    if (this.semantic instanceof GraphQLObjectType) {
      return `/reference/${this.semantic.name}`
    }

    if (this.semantic instanceof GraphQLScalarType) {
      return `/reference/${this.semantic.name}`
    }

    if (this.semantic instanceof GraphQLInterfaceType) {
      return `/reference/${this.semantic.name}`
    }

    if (this.semantic instanceof GraphQLUnionType) {
      return `/reference/${this.semantic.name}`
    }

    if (this.semantic instanceof GraphQLEnumType) {
      return `/reference/${this.semantic.name}`
    }

    if (this.semantic instanceof GraphQLInputObjectType) {
      return `/reference/${this.semantic.name}`
    }

    return null
  }
}

// Cache for the parser instance
let parserPromise: Promise<WebTreeSitter.Parser> | null = null

/**
 * Minimal synthetic node that implements just enough of the WebTreeSitter.Node interface
 * Uses TreeSitterGraphQLNodeType for type safety
 *
 * IMPORTANT: This must be a class with getters to match WebTreeSitter.Node's WASM interface.
 * Plain objects with properties will cause "memory access out of bounds" errors when
 * tree-sitter tries to call the WASM getter functions.
 */
class SyntheticNode {
  constructor(
    public type: TreeSitterGraphQLNodeType,
    private _text: string,
    private _startIndex: number,
    private _endIndex: number,
  ) {}

  // These getters match WebTreeSitter.Node's interface
  get text(): string {
    return this._text
  }

  get startIndex(): number {
    return this._startIndex
  }

  get endIndex(): number {
    return this._endIndex
  }

  get childCount(): number {
    return 0
  }

  get parent(): null {
    return null
  }
}

/**
 * Tracks semantic context while walking the tree-sitter AST
 *
 * This class maintains the current GraphQL execution context as we traverse
 * the syntax tree, allowing us to resolve field references to their schema
 * definitions and validate field access.
 *
 * ## Context Management Strategy
 *
 * The semantic context uses a stack-based approach to track the current type context
 * as we traverse nested GraphQL selections. This is essential for resolving field
 * references since field names are only meaningful within their parent type context.
 *
 * ### Type Stack Management:
 * - Each stack entry contains: { type: GraphQLType, field?: GraphQLField }
 * - The `field` property tracks the field that led us to this type level
 * - Stack depth corresponds to GraphQL selection nesting depth
 * - Root level: operation root type (Query/Mutation/Subscription)
 * - Nested levels: field return types that support sub-selections
 *
 * ### Context Transitions:
 * - `enterOperation()`: Sets root type based on operation type
 * - `enterField()`: Pushes field's return type if it's selectable (Object/Interface)
 * - `exitField()`: Pops from stack when leaving a field's selection set
 * - `enterFragment()`: Switches context to fragment's target type
 *
 * ### Argument Resolution Challenge:
 * Arguments appear in the AST before their parent field context is established,
 * requiring the complex lookup logic documented in the argument parsing section.
 *
 * @example
 * ```typescript
 * const context = new SemanticContext(schema)
 * context.enterOperation('query')     // Stack: [Query]
 * context.enterField('user')          // Stack: [Query, User]
 * const fieldInfo = context.getFieldInfo('name') // Gets User.name field
 * context.exitField()                 // Stack: [Query]
 * ```
 */
class SemanticContext {
  /**
   * Stack of type contexts representing the current selection path.
   * Each entry tracks the type we're currently selecting from and optionally
   * the field that brought us to this type level.
   */
  private typeStack: Array<{ type: GraphQLObjectType | GraphQLInterfaceType; field?: GraphQLField<any, any> }> = []

  /** Current operation type, set when entering an operation definition */
  operationType: 'query' | 'mutation' | 'subscription' | null = null

  /** GraphQL schema used for type lookups and validation */
  schema: GraphQLSchema

  constructor(schema: GraphQLSchema) {
    this.schema = schema
  }

  enterOperation(type: string) {
    this.operationType = type as 'query' | 'mutation' | 'subscription'
    const rootType = type === 'query'
      ? this.schema.getQueryType()
      : type === 'mutation'
      ? this.schema.getMutationType()
      : type === 'subscription'
      ? this.schema.getSubscriptionType()
      : null

    if (rootType) {
      this.typeStack = [{ type: rootType }]
    }
  }

  enterFragment(typeName: string) {
    const type = this.schema.getType(typeName)

    if (type && (isObjectType(type) || isInterfaceType(type))) {
      this.typeStack = [{ type }]
    }
  }

  getFieldInfo(
    fieldName: string,
  ): { parentType: GraphQLObjectType | GraphQLInterfaceType; fieldDef: GraphQLField<any, any> } | null {
    const current = this.typeStack[this.typeStack.length - 1]
    if (!current) return null

    const fields = current.type.getFields()
    const fieldDef = fields[fieldName]

    if (fieldDef) {
      return { parentType: current.type, fieldDef }
    }
    return null
  }

  enterField(fieldName: string) {
    const fieldInfo = this.getFieldInfo(fieldName)
    if (fieldInfo) {
      // Only push to stack if field type is object/interface
      const fieldType = getNamedType(fieldInfo.fieldDef.type)
      if (isObjectType(fieldType) || isInterfaceType(fieldType)) {
        // Push new context with the field that brought us here
        this.typeStack.push({ type: fieldType, field: fieldInfo.fieldDef })
      }
    }
  }

  exitField() {
    // Only pop if we're not at root and the last entry has a field
    // (meaning it was pushed by enterField for an object/interface type)
    if (this.typeStack.length > 1) {
      const last = this.typeStack[this.typeStack.length - 1]
      if (last && last.field) {
        this.typeStack.pop()
      }
    }
  }

  getArgumentInfo(argName: string) {
    const current = this.typeStack[this.typeStack.length - 1]
    if (!current?.field) return null

    const arg = current.field.args.find(a => a.name === argName)
    return arg ? { field: current.field, arg, parentType: current.type } : null
  }

  getCurrentType(): (GraphQLObjectType | GraphQLInterfaceType) | null {
    const current = this.typeStack[this.typeStack.length - 1]
    return current?.type || null
  }

  lookupType(typeName: string) {
    return this.schema.getType(typeName)
  }

  reset() {
    this.typeStack = []
    this.operationType = null
  }
}

/**
 * Parse GraphQL code into interactive tokens with semantic information
 *
 * @param code - The raw GraphQL code to parse
 * @param annotations - CodeHike annotations that might affect rendering
 * @param schema - Optional GraphQL schema for semantic analysis
 * @returns Array of tokens representing the parsed code
 */
export async function parseGraphQLWithTreeSitter(
  code: string,
  annotations: CodeAnnotation[] = [],
  schema?: GraphQLSchema,
): Promise<GraphQLToken[]> {
  // Validate input
  if (!code || typeof code !== 'string') {
    throw new Error('Invalid GraphQL code: code must be a non-empty string')
  }

  // Prevent parsing extremely large documents that could cause performance issues
  if (code.length > 100_000) {
    throw new Error('GraphQL document too large: maximum 100,000 characters allowed')
  }

  // Step 1: Parse with tree-sitter
  const parser = await getParser()
  const tree = parser.parse(code)

  if (!tree) {
    throw new Error('Tree-sitter failed to parse GraphQL code')
  }

  // Check if tree-sitter found syntax errors (disabled for now as it may be too strict)
  // if (tree.rootNode.hasError) {
  //   throw new Error('GraphQL syntax error detected by tree-sitter parser')
  // }

  try {
    // Step 2: Walk tree and attach semantics
    const tokens = collectTokensWithSemantics(tree, code, schema, annotations)

    // Step 3: Add error hint tokens after invalid fields
    const tokensWithHints = addErrorHintTokens(tokens, code, annotations)

    return tokensWithHints
  } finally {
    // ## Tree-sitter Resource Lifecycle Management
    //
    // Tree-sitter creates native WASM objects that must be explicitly freed to prevent memory leaks.
    // The tree object holds references to parsed nodes and internal parser state that won't be
    // garbage collected automatically by JavaScript.
    //
    // Critical cleanup points:
    // 1. Always call tree.delete() in a finally block to ensure cleanup even on errors
    // 2. Do not access tree or any of its nodes after calling delete()
    // 3. The parser instance is cached globally and reused across multiple parsing calls
    //
    // Memory safety: Once tree.delete() is called, all WebTreeSitter.Node references become invalid.
    // Our tokens hold references to these nodes, but only use their text and position properties
    // which are copied during token creation, so the nodes can be safely deleted.
    tree.delete()
  }
}

/**
 * Get or create the tree-sitter parser instance
 */
async function getParser(): Promise<WebTreeSitter.Parser> {
  if (!parserPromise) {
    parserPromise = initializeTreeSitter()
  }
  return parserPromise
}

/**
 * Initialize tree-sitter with the GraphQL grammar
 */
async function initializeTreeSitter(): Promise<WebTreeSitter.Parser> {
  try {
    // Handle different environments
    const isNode = typeof process !== 'undefined' && process.versions && process.versions.node

    if (isNode) {
      // Node.js environment (tests)
      const fs = await import('node:fs/promises')
      const path = await import('node:path')

      // Find the actual WASM files in node_modules
      const treeSitterWasmPath = path.join(process.cwd(), 'node_modules/web-tree-sitter/tree-sitter.wasm')
      const graphqlWasmPath = path.join(process.cwd(), 'node_modules/tree-sitter-graphql-grammar-wasm/grammar.wasm')

      await WebTreeSitter.Parser.init({
        locateFile: (filename: string) => {
          if (filename === 'tree-sitter.wasm') {
            return treeSitterWasmPath
          }
          return filename
        },
      })

      const parser = new WebTreeSitter.Parser()
      const wasmBuffer = await fs.readFile(graphqlWasmPath)
      const GraphQL = await WebTreeSitter.Language.load(new Uint8Array(wasmBuffer))
      parser.setLanguage(GraphQL)

      return parser
    } else {
      // Browser/Vite environment
      await WebTreeSitter.Parser.init({
        locateFile: (filename: string) => {
          if (filename === 'tree-sitter.wasm') {
            return treeSitterWasmUrl
          }
          return filename
        },
      })

      const parser = new WebTreeSitter.Parser()

      // Fetch the WASM file as a buffer
      const response = await fetch(graphqlWasmUrl)
      if (!response.ok) {
        throw new Error(
          `Failed to load GraphQL grammar file: ${response.status} ${response.statusText}. `
            + `This may indicate a network issue or missing grammar file.`,
        )
      }

      const wasmBuffer = await response.arrayBuffer()

      if (wasmBuffer.byteLength === 0) {
        throw new Error('GraphQL grammar file is empty or corrupted')
      }

      const GraphQL = await WebTreeSitter.Language.load(new Uint8Array(wasmBuffer))
      parser.setLanguage(GraphQL)

      return parser
    }
  } catch (error) {
    // Enhance error messages for common issues
    if (error instanceof Error) {
      if (error.message.includes('fetch')) {
        throw new Error(`Tree-sitter initialization failed: ${error.message}. Check your network connection.`)
      }
      if (error.message.includes('Language.load')) {
        throw new Error(`Failed to load GraphQL grammar: ${error.message}. The grammar file may be corrupted.`)
      }
    }
    throw error
  }
}

/**
 * Add error hint tokens after invalid fields
 */
function addErrorHintTokens(
  tokens: GraphQLToken[],
  code: string,
  annotations: CodeAnnotation[],
): GraphQLToken[] {
  const tokensWithHints: GraphQLToken[] = []
  const processedIndices = new Set<number>()

  // Count invalid fields for debugging
  let invalidFieldCount = 0
  tokens.forEach(t => {
    if (t.semantic && 'kind' in t.semantic && t.semantic.kind === 'InvalidField') {
      invalidFieldCount++
    }
  })

  if (invalidFieldCount > 10) {
    // Too many invalid fields - likely a schema mismatch
    // Return tokens without error hints to avoid corrupting display
    console.warn(`Polen: ${invalidFieldCount} invalid fields detected. Schema may not match queries.`)
    return tokens
  }

  for (let i = 0; i < tokens.length; i++) {
    const token = tokens[i]!

    // Skip if we've already processed this token (due to lookahead for arguments)
    if (processedIndices.has(i)) {
      continue
    }

    tokensWithHints.push(token)
    processedIndices.add(i)

    // Check if this is an invalid field
    if (token.semantic && 'kind' in token.semantic && token.semantic.kind === 'InvalidField') {
      // Look ahead to find where the field ends (after arguments if present)
      let fieldEndIndex = i
      let j = i + 1

      // Skip whitespace
      while (j < tokens.length && tokens[j]!.treeSitterNode.type === 'whitespace') {
        j++
      }

      // Check if we have arguments starting with '('
      if (j < tokens.length && tokens[j]!.text === '(') {
        // Find the matching closing ')'
        let parenDepth = 1
        j++ // move past the opening '('

        while (j < tokens.length && parenDepth > 0) {
          const t = tokens[j]!
          if (t.text === '(') parenDepth++
          else if (t.text === ')') parenDepth--
          j++
        }

        // j is now past the closing ')'
        fieldEndIndex = j - 1

        // Add all tokens that are part of the field's arguments
        for (let k = i + 1; k <= fieldEndIndex; k++) {
          if (k < tokens.length && !processedIndices.has(k)) {
            tokensWithHints.push(tokens[k]!)
            processedIndices.add(k)
          }
        }
      }

      // Now add the error hint after the complete field (including arguments)
      const lastFieldToken = tokens[fieldEndIndex] || token
      const hintText = ' ← No such field'
      const hintToken = new UnifiedToken(
        createSyntheticNode(
          'error_hint',
          hintText,
          lastFieldToken.end,
          lastFieldToken.end + hintText.length,
        ),
        undefined,
        annotations,
      )
      tokensWithHints.push(hintToken)
    }
  }

  return tokensWithHints
}

/**
 * Walk tree-sitter AST and collect tokens with semantic information
 */
function collectTokensWithSemantics(
  tree: WebTreeSitter.Tree,
  code: string,
  schema: GraphQLSchema | undefined,
  annotations: CodeAnnotation[],
): GraphQLToken[] {
  const tokens: GraphQLToken[] = []
  const cursor = tree.walk()
  const context = schema ? new SemanticContext(schema) : null
  let lastEnd = 0

  function processNode() {
    const node = cursor.currentNode
    if (!node) return

    // Handle different node types for semantic context
    if (context) {
      if (node.type === 'operation_definition') {
        // Find the operation type child
        const operationType = findChildByType(cursor, 'operation_type')
        if (operationType) {
          context.enterOperation(operationType.text)
        }
      }

      if (node.type === 'fragment_definition') {
        // Find the type condition
        const typeCondition = findChildByType(cursor, 'type_condition')
        if (typeCondition) {
          const typeName = findChildByType(cursor, 'named_type', typeCondition)
          if (typeName) {
            const nameNode = findChildByType(cursor, 'name', typeName)
            if (nameNode) {
              context.enterFragment(nameNode.text)
            }
          }
        }
      }

      // We don't need special handling for selection_set anymore
      // Context is managed at the field level
    }

    // Collect leaf tokens with semantic info
    // Special case: string_value, int_value, float_value nodes should be collected as whole tokens
    // even though they have children (the quotes or signs)
    const isValueNode = node.type === 'string_value' || node.type === 'int_value' || node.type === 'float_value'
    const shouldCollectToken = (node.childCount === 0 || isValueNode) && node.text.trim() !== ''

    if (shouldCollectToken) {
      // Add whitespace before this token if needed
      if (node.startIndex > lastEnd) {
        const whitespace = code.slice(lastEnd, node.startIndex)
        tokens.push(
          new UnifiedToken(
            createWhitespaceNode(whitespace, lastEnd, node.startIndex),
            undefined,
            annotations,
          ),
        )
      }

      // Determine semantic info for this token
      let semantic: SemanticNode | undefined

      if (context && node.type === 'name') {
        const parent = cursor.currentNode.parent

        if (parent?.type === 'field') {
          // This is a field name - get info from current context
          const fieldInfo = context.getFieldInfo(node.text)
          const currentType = context.getCurrentType()

          if (fieldInfo) {
            semantic = {
              kind: 'OutputField',
              parentType: fieldInfo.parentType,
              fieldDef: fieldInfo.fieldDef,
            }
            // Enter this field's context for processing its selection set
            context.enterField(node.text)
          } else if (currentType) {
            // Field doesn't exist - mark as invalid
            semantic = {
              kind: 'InvalidField',
              fieldName: node.text,
              parentType: currentType,
            }
          }
        } else if (parent?.type === 'named_type') {
          // This is a type reference
          const type = context.lookupType(node.text)
          if (type) {
            // Check if it's one of the types we support as semantic nodes
            if (
              type instanceof GraphQLObjectType
              || type instanceof GraphQLScalarType
              || type instanceof GraphQLInterfaceType
              || type instanceof GraphQLUnionType
              || type instanceof GraphQLEnumType
              || type instanceof GraphQLInputObjectType
            ) {
              semantic = type
            }
          }
        } else if (parent?.type === 'operation_definition') {
          // This is an operation name
          semantic = {
            kind: 'Operation',
            type: context.operationType || 'query',
            name: node.text,
          }
        } else if (parent?.type === 'fragment_definition') {
          // This is a fragment name - for now just mark it as a fragment
          semantic = {
            kind: 'Fragment',
            name: node.text,
            onType: context.getCurrentType()!, // We'll have the type from enterFragment
          }
        } else if (parent?.type === 'argument') {
          // This is an argument name
          //
          // ## Complex Argument Parsing Logic
          //
          // Arguments require complex tree traversal because they appear in the tree-sitter AST
          // before the semantic context has been updated for their parent field. This creates
          // a chicken-and-egg problem where we need the field to identify the argument, but
          // the field hasn't been processed yet.
          //
          // Tree structure: field > arguments > argument > name
          // Processing order: argument names are parsed before field context is established
          //
          // Our solution is to traverse up the AST to find the field node, then look for that
          // field in both the root operation type and the current type context. We check the
          // root type first because top-level fields (like Query.pokemon) are most common.

          let argumentsNode = parent.parent
          if (argumentsNode && argumentsNode.type === 'arguments') {
            let fieldNode = argumentsNode.parent
            if (fieldNode && fieldNode.type === 'field') {
              // Find the field name node within the field node
              for (let i = 0; i < fieldNode.childCount; i++) {
                const child = fieldNode.child(i)
                if (child && child.type === 'name') {
                  // We need to find the parent type that contains this field
                  // Start with the root type based on the operation type (query/mutation/subscription)
                  const rootType = context.schema.getQueryType() || context.schema.getMutationType()
                    || context.schema.getSubscriptionType()

                  if (rootType) {
                    // First check if the field exists on the root type (most common case)
                    let field = rootType.getFields()[child.text]
                    let parentType: GraphQLObjectType | GraphQLInterfaceType = rootType

                    // If not found on root, check the current type in our semantic context
                    // This handles nested field arguments like User.posts(limit: 10)
                    if (!field) {
                      const currentType = context.getCurrentType()
                      if (currentType) {
                        field = currentType.getFields()[child.text]
                        parentType = currentType
                      }
                    }

                    if (field && parentType) {
                      const arg = field.args.find((a: GraphQLArgument) => a.name === node.text)
                      if (arg) {
                        semantic = {
                          kind: 'Argument',
                          parentType: parentType,
                          parentField: field,
                          argumentDef: arg,
                        }
                      }
                    }
                  }
                  break
                }
              }
            }
          }
        } else if (parent?.type === 'variable') {
          // This is a variable name (without the $)
          semantic = {
            kind: 'Variable',
            name: node.text,
          }
        } else if (parent?.type === 'variable_definition') {
          // This is a variable definition in the operation header
          semantic = {
            kind: 'Variable',
            name: node.text,
          }
        }
      } else if (context && node.type === 'variable' && node.text.startsWith('$')) {
        // This is the full variable including $ (usage in arguments or directives)
        semantic = {
          kind: 'Variable',
          name: node.text.slice(1),
        }
      }

      const token = new UnifiedToken(
        node,
        semantic,
        annotations,
      )

      tokens.push(token)

      lastEnd = node.endIndex
    }

    // Traverse children (but skip children of value nodes since we collect them as whole tokens)
    if (!isValueNode && cursor.gotoFirstChild()) {
      do {
        processNode()
      } while (cursor.gotoNextSibling())
      cursor.gotoParent()

      // Handle context exit
      if (context && node.type === 'field') {
        // Only exit field context if this field has a selection set
        // (meaning it's an object/interface type that pushed to the stack)
        const hasSelectionSet = node.childCount > 0 && node.children.some(
          child => child?.type === 'selection_set',
        )
        if (hasSelectionSet) {
          context.exitField()
        }
      } else if (context && (node.type === 'operation_definition' || node.type === 'fragment_definition')) {
        // Reset context when exiting operation or fragment
        context.reset()
      }
    }
  }

  processNode()

  // Add final whitespace if needed
  if (lastEnd < code.length) {
    const remaining = code.slice(lastEnd)
    tokens.push(
      new UnifiedToken(
        createWhitespaceNode(remaining, lastEnd, code.length),
        undefined,
        annotations,
      ),
    )
  }

  return tokens
}

/**
 * Helper to find a child node by type
 */
function findChildByType(
  cursor: WebTreeSitter.TreeCursor,
  type: string,
  node?: WebTreeSitter.Node,
): WebTreeSitter.Node | null {
  const targetNode = node || cursor.currentNode
  if (!targetNode) return null

  for (let i = 0; i < targetNode.childCount; i++) {
    const child = targetNode.child(i)
    if (child && child.type === type) {
      return child
    }
  }
  return null
}

/**
 * Create a pseudo tree-sitter node for whitespace
 */
function createWhitespaceNode(text: string, start: number, end: number): WebTreeSitter.Node {
  // Create a synthetic node with proper getter interface
  const node = new SyntheticNode('whitespace', text, start, end)
  return node as unknown as WebTreeSitter.Node
}

/**
 * Create a pseudo tree-sitter node for synthetic content
 *
 * ## Annotation Architecture
 *
 * Polen uses synthetic tree-sitter nodes to inject additional content into GraphQL code blocks.
 * This approach was chosen after considering several alternatives:
 *
 * ### Current Approach: Synthetic Nodes
 * We create fake tree-sitter nodes that implement just enough of the Node interface to flow
 * through our token rendering pipeline. This is used for error hints that appear after invalid fields.
 *
 * **When to use**: When you need to add new content to the code block (not just style existing content)
 *
 * ### Alternative Approaches Considered:
 *
 * 1. **CodeHike Annotations**
 *    - Use CodeHike's built-in InlineAnnotation/BlockAnnotation system
 *    - Pros: Works with CodeHike's architecture, composable with other handlers
 *    - Cons: More complex, requires understanding CodeHike's annotation pipeline
 *    - Best for: Complex features like collapsible sections, tabs
 *
 * 2. **Post-Processing During Render**
 *    - Keep tokens unchanged, add content during the rendering phase
 *    - Pros: Simpler, no fake nodes needed
 *    - Cons: Rendering logic becomes more complex, harder to test
 *    - Best for: Simple conditional content
 *
 * 3. **Token Metadata/Props**
 *    - Add annotation data to token properties rather than creating new tokens
 *    - Pros: Clean data model, easy to test
 *    - Cons: Can't add new content, only modify existing tokens
 *    - Best for: Styling annotations (highlights, emphasis, underlines)
 *
 * ### Guidelines for Future Annotations:
 *
 * - **Styling only** (highlights, emphasis): Use token metadata/props
 * - **Adding content** (error hints, tooltips): Use synthetic nodes (current approach)
 * - **Complex UI** (collapsible, tabs): Consider CodeHike annotation handlers
 * - **User-defined annotations**: Choose based on what the annotation does
 *
 * The synthetic node approach works well for Polen's error hints because we're actually
 * inserting new text content ("← No such field") that needs to be positioned and styled
 * like a regular token.
 */
function createSyntheticNode(
  type: TreeSitterGraphQLNodeType,
  text: string,
  start: number,
  end: number,
): WebTreeSitter.Node {
  // Create a synthetic node with proper getter interface
  const node = new SyntheticNode(type, text, start, end)
  return node as unknown as WebTreeSitter.Node
}