lib/graphql/language/visitor.rb



# frozen_string_literal: true
module GraphQL
  module Language
    # Depth-first traversal through the tree, calling hooks at each stop.
    #
    # @example Create a visitor counting certain field names
    #   class NameCounter < GraphQL::Language::Visitor
    #     def initialize(document, field_name)
    #       super(document)
    #       @field_name = field_name
    #       @count = 0
    #     end
    #
    #     attr_reader :count
    #
    #     def on_field(node, parent)
    #       # if this field matches our search, increment the counter
    #       if node.name == @field_name
    #         @count += 1
    #       end
    #       # Continue visiting subfields:
    #       super
    #     end
    #   end
    #
    #   # Initialize a visitor
    #   visitor = NameCounter.new(document, "name")
    #   # Run it
    #   visitor.visit
    #   # Check the result
    #   visitor.count
    #   # => 3
    class Visitor
      # If any hook returns this value, the {Visitor} stops visiting this
      # node right away
      # @deprecated Use `super` to continue the visit; or don't call it to halt.
      SKIP = :_skip

      class DeleteNode; end

      # When this is returned from a visitor method,
      # Then the `node` passed into the method is removed from `parent`'s children.
      DELETE_NODE = DeleteNode.new

      def initialize(document)
        @document = document
        @visitors = {}
        @result = nil
      end

      # @return [GraphQL::Language::Nodes::Document] The document with any modifications applied
      attr_reader :result

      # Get a {NodeVisitor} for `node_class`
      # @param node_class [Class] The node class that you want to listen to
      # @return [NodeVisitor]
      #
      # @example Run a hook whenever you enter a new Field
      #   visitor[GraphQL::Language::Nodes::Field] << ->(node, parent) { p "Here's a field" }
      # @deprecated see `on_` methods, like {#on_field}
      def [](node_class)
        @visitors[node_class] ||= NodeVisitor.new
      end

      # Visit `document` and all children, applying hooks as you go
      # @return [void]
      def visit
        # `@document` may be any kind of node:
        visit_method = :"#{@document.visit_method}_with_modifications"
        result = public_send(visit_method, @document, nil)
        @result = if result.is_a?(Array)
          result.first
        else
          # The node wasn't modified
          @document
        end
      end

      # We don't use `alias` here because it breaks `super`
      def self.make_visit_methods(ast_node_class)
        node_method = ast_node_class.visit_method
        children_of_type = ast_node_class.children_of_type
        child_visit_method = :"#{node_method}_children"

        class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
          # The default implementation for visiting an AST node.
          # It doesn't _do_ anything, but it continues to visiting the node's children.
          # To customize this hook, override one of its make_visit_methods (or the base method?)
          # in your subclasses.
          #
          # For compatibility, it calls hook procs, too.
          # @param node [GraphQL::Language::Nodes::AbstractNode] the node being visited
          # @param parent [GraphQL::Language::Nodes::AbstractNode, nil] the previously-visited node, or `nil` if this is the root node.
          # @return [Array, nil] If there were modifications, it returns an array of new nodes, otherwise, it returns `nil`.
          def #{node_method}(node, parent)
            if node.equal?(DELETE_NODE)
              # This might be passed to `super(DELETE_NODE, ...)`
              # by a user hook, don't want to keep visiting in that case.
              [node, parent]
            else
              # Run hooks if there are any
              new_node = node
              no_hooks = !@visitors.key?(node.class)
              if no_hooks || begin_visit(new_node, parent)
                #{
                  if method_defined?(child_visit_method)
                    "new_node = #{child_visit_method}(new_node)"
                  elsif children_of_type
                    children_of_type.map do |child_accessor, child_class|
                      "node.#{child_accessor}.each do |child_node|
                        new_child_and_node = #{child_class.visit_method}_with_modifications(child_node, new_node)
                        # Reassign `node` in case the child hook makes a modification
                        if new_child_and_node.is_a?(Array)
                          new_node = new_child_and_node[1]
                        end
                      end"
                    end.join("\n")
                  else
                    ""
                  end
                }
              end
              end_visit(new_node, parent) unless no_hooks

              if new_node.equal?(node)
                [node, parent]
              else
                [new_node, parent]
              end
            end
          end

          def #{node_method}_with_modifications(node, parent)
            new_node_and_new_parent = #{node_method}(node, parent)
            apply_modifications(node, parent, new_node_and_new_parent)
          end
        RUBY
      end

      def on_document_children(document_node)
        new_node = document_node
        document_node.children.each do |child_node|
          visit_method = :"#{child_node.visit_method}_with_modifications"
          new_child_and_node = public_send(visit_method, child_node, new_node)
          # Reassign `node` in case the child hook makes a modification
          if new_child_and_node.is_a?(Array)
            new_node = new_child_and_node[1]
          end
        end
        new_node
      end

      def on_field_children(new_node)
        new_node.arguments.each do |arg_node| # rubocop:disable Development/ContextIsPassedCop
          new_child_and_node = on_argument_with_modifications(arg_node, new_node)
          # Reassign `node` in case the child hook makes a modification
          if new_child_and_node.is_a?(Array)
            new_node = new_child_and_node[1]
          end
        end
        new_node = visit_directives(new_node)
        new_node = visit_selections(new_node)
        new_node
      end

      def visit_directives(new_node)
        new_node.directives.each do |dir_node|
          new_child_and_node = on_directive_with_modifications(dir_node, new_node)
          # Reassign `node` in case the child hook makes a modification
          if new_child_and_node.is_a?(Array)
            new_node = new_child_and_node[1]
          end
        end
        new_node
      end

      def visit_selections(new_node)
        new_node.selections.each do |selection|
          new_child_and_node = case selection
          when GraphQL::Language::Nodes::Field
            on_field_with_modifications(selection, new_node)
          when GraphQL::Language::Nodes::InlineFragment
            on_inline_fragment_with_modifications(selection, new_node)
          when GraphQL::Language::Nodes::FragmentSpread
            on_fragment_spread_with_modifications(selection, new_node)
          else
            raise ArgumentError, "Invariant: unexpected field selection #{selection.class} (#{selection.inspect})"
          end
          # Reassign `node` in case the child hook makes a modification
          if new_child_and_node.is_a?(Array)
            new_node = new_child_and_node[1]
          end
        end
        new_node
      end

      def on_fragment_definition_children(new_node)
        new_node = visit_directives(new_node)
        new_node = visit_selections(new_node)
        new_node
      end

      alias :on_inline_fragment_children :on_fragment_definition_children

      def on_operation_definition_children(new_node)
        new_node.variables.each do |arg_node|
          new_child_and_node = on_variable_definition_with_modifications(arg_node, new_node)
          # Reassign `node` in case the child hook makes a modification
          if new_child_and_node.is_a?(Array)
            new_node = new_child_and_node[1]
          end
        end
        new_node = visit_directives(new_node)
        new_node = visit_selections(new_node)
        new_node
      end

      def on_argument_children(new_node)
        new_node.children.each do |value_node|
          new_child_and_node = case value_node
          when Language::Nodes::VariableIdentifier
            on_variable_identifier_with_modifications(value_node, new_node)
          when Language::Nodes::InputObject
            on_input_object_with_modifications(value_node, new_node)
          when Language::Nodes::Enum
            on_enum_with_modifications(value_node, new_node)
          when Language::Nodes::NullValue
            on_null_value_with_modifications(value_node, new_node)
          else
            raise ArgumentError, "Invariant: unexpected argument value node #{value_node.class} (#{value_node.inspect})"
          end
          # Reassign `node` in case the child hook makes a modification
          if new_child_and_node.is_a?(Array)
            new_node = new_child_and_node[1]
          end
        end
        new_node
      end

      [
        Language::Nodes::Argument,
        Language::Nodes::Directive,
        Language::Nodes::DirectiveDefinition,
        Language::Nodes::DirectiveLocation,
        Language::Nodes::Document,
        Language::Nodes::Enum,
        Language::Nodes::EnumTypeDefinition,
        Language::Nodes::EnumTypeExtension,
        Language::Nodes::EnumValueDefinition,
        Language::Nodes::Field,
        Language::Nodes::FieldDefinition,
        Language::Nodes::FragmentDefinition,
        Language::Nodes::FragmentSpread,
        Language::Nodes::InlineFragment,
        Language::Nodes::InputObject,
        Language::Nodes::InputObjectTypeDefinition,
        Language::Nodes::InputObjectTypeExtension,
        Language::Nodes::InputValueDefinition,
        Language::Nodes::InterfaceTypeDefinition,
        Language::Nodes::InterfaceTypeExtension,
        Language::Nodes::ListType,
        Language::Nodes::NonNullType,
        Language::Nodes::NullValue,
        Language::Nodes::ObjectTypeDefinition,
        Language::Nodes::ObjectTypeExtension,
        Language::Nodes::OperationDefinition,
        Language::Nodes::ScalarTypeDefinition,
        Language::Nodes::ScalarTypeExtension,
        Language::Nodes::SchemaDefinition,
        Language::Nodes::SchemaExtension,
        Language::Nodes::TypeName,
        Language::Nodes::UnionTypeDefinition,
        Language::Nodes::UnionTypeExtension,
        Language::Nodes::VariableDefinition,
        Language::Nodes::VariableIdentifier,
      ].each do |ast_node_class|
        make_visit_methods(ast_node_class)
      end

      private

      def apply_modifications(node, parent, new_node_and_new_parent)
        if new_node_and_new_parent.is_a?(Array)
          new_node = new_node_and_new_parent[0]
          new_parent = new_node_and_new_parent[1]
          if new_node.is_a?(Nodes::AbstractNode) && !node.equal?(new_node)
            # The user-provided hook returned a new node.
            new_parent = new_parent && new_parent.replace_child(node, new_node)
            return new_node, new_parent
          elsif new_node.equal?(DELETE_NODE)
            # The user-provided hook requested to remove this node
            new_parent = new_parent && new_parent.delete_child(node)
            return nil, new_parent
          elsif new_node_and_new_parent.none? { |n| n == nil || n.class < Nodes::AbstractNode }
            # The user-provided hook returned an array of who-knows-what
            # return nil here to signify that no changes should be made
            nil
          else
            new_node_and_new_parent
          end
        else
          # The user-provided hook didn't make any modifications.
          # In fact, the hook might have returned who-knows-what, so
          # ignore the return value and use the original values.
          new_node_and_new_parent
        end
      end

      def begin_visit(node, parent)
        node_visitor = self[node.class]
        self.class.apply_hooks(node_visitor.enter, node, parent)
      end

      # Should global `leave` visitors come first or last?
      def end_visit(node, parent)
        node_visitor = self[node.class]
        self.class.apply_hooks(node_visitor.leave, node, parent)
      end

      # If one of the visitors returns SKIP, stop visiting this node
      def self.apply_hooks(hooks, node, parent)
        hooks.each do |proc|
          return false if proc.call(node, parent) == SKIP
        end
        true
      end

      # Collect `enter` and `leave` hooks for classes in {GraphQL::Language::Nodes}
      #
      # Access {NodeVisitor}s via {GraphQL::Language::Visitor#[]}
      class NodeVisitor
        # @return [Array<Proc>] Hooks to call when entering a node of this type
        attr_reader :enter
        # @return [Array<Proc>] Hooks to call when leaving a node of this type
        attr_reader :leave

        def initialize
          @enter = []
          @leave = []
        end

        # Shorthand to add a hook to the {#enter} array
        # @param hook [Proc] A hook to add
        def <<(hook)
          enter << hook
        end
      end
    end
  end
end