rubocop-graphql 1.6.0 → 1.8.0

data/lib/rubocop/cop/graphql/object_description.rb

@@ -6,6 +6,19 @@ module RuboCop
       #  This cop checks if a type (object, input, interface, scalar, union,
       #  mutation, subscription, and resolver) has a description.
       #
+      #  Only classes that actually declare a GraphQL type are checked: those whose
+      #  superclass resolves to a GraphQL base (`Object`, `InputObject`, `Union`,
+      #  `Enum`, `Scalar`, or anything ending in `Mutation`, `Subscription` or
+      #  `Resolver`), plus modules that `include` an `*Interface` base. Plain Ruby
+      #  classes that happen to live alongside types - error classes, analyzers,
+      #  validators, loaders, generators - are skipped, so they no longer need to be
+      #  silenced one by one.
+      #
+      #  Two kinds of real type declarations are also skipped, because neither
+      #  surfaces a description in the schema: abstract `Base*` types that other
+      #  types inherit from, and (unless `IgnoreRootTypes` is disabled) the root
+      #  operation types `Query`, `Mutation` and `Subscription`.
+      #
       # @example
       #   # good
       #
@@ -20,44 +33,185 @@ module RuboCop
       #     # ...
       #   end
       #
+      # @example
+      #   # good - not a GraphQL type, so no description is expected
+      #
+      #   class TrackingInfoNotAvailable < StandardError; end
+      #   class UserLoader < GraphQL::Batch::Loader; end
+      #
+      # @example
+      #   # good - abstract base and root operation types carry no description
+      #
+      #   class Types::BaseObject < GraphQL::Schema::Object; end
+      #   class Types::Query < Types::BaseObject; end
+      #
+      # @example AdditionalTypeBases: [] (default)
+      #   # good - `ApplicationType` is not a recognized GraphQL base, so this
+      #   # class is not checked
+      #
+      #   class Types::UserType < ApplicationType
+      #   end
+      #
+      # @example AdditionalTypeBases: ['ApplicationType']
+      #   # bad - `ApplicationType` is now treated as a GraphQL base
+      #
+      #   class Types::UserType < ApplicationType
+      #   end
+      #
       class ObjectDescription < Base
-        include RuboCop::GraphQL::NodePattern
         include RuboCop::GraphQL::DescriptionMethod
 
         MSG = "Missing type description"
 
-        # @!method interface?(node)
-        def_node_matcher :interface?, <<~PATTERN
-          (send nil? :include (const ...))
-        PATTERN
+        # Base class names that mark a GraphQL type when they match exactly, or with
+        # a `Base` prefix (`GraphQL::Schema::Object`, `Types::BaseObject`).
+        # Ambiguous words are deliberately not matched as suffixes, so a plain Ruby
+        # `ValueObject` base is not mistaken for a GraphQL one. `Interface` is absent
+        # on purpose: graphql-ruby interfaces are modules, so a *class* inheriting an
+        # `*::Interface` constant is always some other abstract base.
+        EXACT_BASES = %w[Object InputObject Union Enum Scalar].freeze
+
+        # These read unambiguously as GraphQL even inside a longer name, so they are
+        # matched as suffixes (`RelayClassicMutation`, `Base::PermissionedMutation`).
+        SUFFIX_BASES = %w[Mutation Subscription Resolver].freeze
+
+        # A base named exactly `Base` (`Resolvers::Base`) is only a GraphQL base when
+        # it sits in a namespace that says so.
+        GRAPHQL_NAMESPACES = %w[
+          Types Mutations Subscriptions Resolvers Inputs Interfaces Unions Enums Scalars
+        ].freeze
+
+        # GraphQL reserves these names for the root operation types.
+        ROOT_TYPE_NAMES = %w[Query Mutation Subscription].freeze
+
+        # `Base`, or `Base` followed by another word - the naming convention for the
+        # abstract types that other types inherit from (`BaseObject`, `BaseInterface`).
+        ABSTRACT_BASE_NAME = /\ABase(?:[A-Z]|\z)/
+
+        # Sorbet's `T` namespace is reserved, and `T::Enum` / `T::Struct` collide with
+        # the base names above.
+        SORBET_NAMESPACE = :T
 
         def on_class(node)
-          return if child_nodes(node).find { |child_node| has_description?(child_node) }
+          return unless graphql_type_class?(node)
+          return if exempt_type?(node)
+          return if described_or_root_named?(node)
 
           add_offense(node.identifier)
         end
 
         def on_module(node)
-          return if child_nodes(node).none? { |child_node| interface?(child_node) }
+          return if abstract_base?(node)
+          return unless undescribed_interface_module?(node)
 
-          if child_nodes(node).none? { |child_node| has_description?(child_node) }
-            add_offense(node.identifier)
-          end
+          add_offense(node.identifier)
         end
 
         private
 
-        def has_description?(node)
-          description_method_call?(node)
+        # Abstract bases and the root operation types are real GraphQL declarations,
+        # but neither surfaces a description in the schema.
+        def exempt_type?(node)
+          return true if abstract_base?(node)
+
+          ignore_root_types? && ROOT_TYPE_NAMES.include?(type_name(node))
+        end
+
+        def abstract_base?(node)
+          ABSTRACT_BASE_NAME.match?(type_name(node))
+        end
+
+        def type_name(node)
+          node.identifier.short_name.to_s
+        end
+
+        def graphql_type_class?(node)
+          superclass = node.parent_class
+          return false if superclass.nil? || !superclass.const_type?
+          return false if superclass.namespace&.short_name == SORBET_NAMESPACE
+
+          graphql_base?(superclass)
         end
 
-        def child_nodes(node)
-          if node.body.instance_of? RuboCop::AST::Node
-            node.body.child_nodes
-          else
-            node.child_nodes
+        def graphql_base?(const_node)
+          name = const_node.short_name.to_s
+          return true if additional_type_bases.include?(name)
+          return graphql_namespace?(const_node) if name == "Base"
+          return true if SUFFIX_BASES.any? { |suffix| name.end_with?(suffix) }
+
+          EXACT_BASES.include?(name.delete_prefix("Base"))
+        end
+
+        def graphql_namespace?(const_node)
+          namespace = const_node.namespace
+          return false if namespace.nil? || !namespace.const_type?
+
+          GRAPHQL_NAMESPACES.include?(namespace.short_name.to_s)
+        end
+
+        # A method call with no explicit receiver (e.g. `description "..."`,
+        # `include Foo`) - the shape of a GraphQL type DSL declaration.
+        def bare_call?(node)
+          node.send_type? && node.receiver.nil?
+        end
+
+        # Single pass over the module body: an interface module both `include`s an
+        # `*Interface` base and (when compliant) declares a `description`.
+        def undescribed_interface_module?(node)
+          interface = false
+          described = false
+
+          body_nodes(node).each do |child|
+            described ||= description_method_call?(child)
+            interface ||= interface_include?(child)
+          end
+
+          interface && !described
+        end
+
+        def interface_include?(node)
+          return false unless bare_call?(node) && node.method?(:include)
+
+          arg = node.first_argument
+          return false unless arg&.const_type?
+
+          name = arg.short_name.to_s
+          name.end_with?("Interface") || additional_type_bases.include?(name)
+        end
+
+        # Single pass over the class body: a `description` satisfies the cop, and a
+        # `graphql_name "Query"` marks a root operation type declared under some
+        # other class name, which is exempt like a class named `Query` itself.
+        def described_or_root_named?(node)
+          body_nodes(node).any? do |child|
+            description_method_call?(child) || root_graphql_name?(child)
           end
         end
+
+        def root_graphql_name?(node)
+          return false unless ignore_root_types?
+          return false unless bare_call?(node) && node.method?(:graphql_name)
+
+          arg = node.first_argument
+          return false unless arg&.str_type?
+
+          ROOT_TYPE_NAMES.include?(arg.value)
+        end
+
+        def body_nodes(node)
+          body = node.body
+          return [] if body.nil?
+
+          body.begin_type? ? body.child_nodes : [body]
+        end
+
+        def ignore_root_types?
+          cop_config.fetch("IgnoreRootTypes", true)
+        end
+
+        def additional_type_bases
+          @additional_type_bases ||= Array(cop_config["AdditionalTypeBases"])
+        end
       end
     end
   end

data/lib/rubocop/cop/graphql/ordered_fields.rb

@@ -50,7 +50,26 @@ module RuboCop
         PATTERN
 
         def on_class(node)
-          field_declarations(node).each_cons(2) do |previous, current|
+          check_field_ordering(direct_field_declarations(node))
+        end
+
+        alias on_module on_class
+
+        def on_block(node)
+          return if node.method?(:field)
+          return unless node.each_ancestor(:class, :module).any?
+
+          fields = field_declarations(node).select { |f| f.each_ancestor(:block).first == node }
+          check_field_ordering(fields)
+        end
+
+        alias on_itblock on_block
+        alias on_numblock on_block
+
+        private
+
+        def check_field_ordering(fields)
+          fields.each_cons(2) do |previous, current|
             next unless consecutive_fields(previous, current)
             next if correct_order?(field_name(previous), field_name(current))
 
@@ -58,9 +77,19 @@ module RuboCop
           end
         end
 
-        alias on_module on_class
+        def direct_field_declarations(node)
+          field_declarations(node).select { |field| direct_child_field?(field, node) }
+        end
 
-        private
+        def direct_child_field?(field_node, class_node)
+          return false unless field_node.each_ancestor(:class, :module).first == class_node
+
+          field_node.each_ancestor(:block).none? do |block_ancestor|
+            next false if block_ancestor.each_ancestor(:class, :module).first != class_node
+
+            !block_ancestor.method?(:field)
+          end
+        end
 
         def consecutive_fields(previous, current)
           return true if cop_config["Groups"] == false

data/lib/rubocop/cop/graphql/unused_argument.rb

@@ -109,7 +109,7 @@ module RuboCop
             node.node_parts[0]
           end.to_set
           declared_args = declared_arg_nodes.map { |node| RuboCop::GraphQL::Argument.new(node) }
-          declared_args.map(&method(:arg_name)).uniq.reject do |declared_arg_name|
+          declared_args.map(&:keyword).uniq.reject do |declared_arg_name|
             resolve_method_kwargs_names.include?(declared_arg_name)
           end
         end
@@ -147,26 +147,6 @@ module RuboCop
           node.source_range.end
         end
 
-        def inferred_arg_name(name_as_string)
-          case name_as_string
-          when /_id$/
-            name_as_string.sub(/_id$/, "").to_sym
-          when /_ids$/
-            name_as_string.sub(/_ids$/, "")
-                          .sub(/([^s])$/, "\\1s")
-                          .to_sym
-          else
-            name_as_string.to_sym
-          end
-        end
-
-        def arg_name(declared_arg)
-          return declared_arg.as if declared_arg.kwargs.as
-          return inferred_arg_name(declared_arg.name.to_s) if declared_arg.kwargs.loads
-
-          declared_arg.name
-        end
-
         def scoped_node?(node)
           scope_changing_syntax?(node) || block_or_lambda?(node)
         end

data/lib/rubocop/cop/graphql/useless_method_option.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module GraphQL
+      #  This cop detects `resolver_method:` or `method:` options that have no
+      #  effect, either because:
+      #
+      #  - the same field also sets `resolver:` -- graphql-ruby always calls
+      #    the resolver class's own resolver_method once `resolver:` is set,
+      #    silently ignoring both `resolver_method:` and `method:` regardless
+      #    of whether a method by either name exists; or
+      #  - a method matching the field's own plain name is also defined on the
+      #    type -- that method is checked (and wins) before `method:` is ever
+      #    considered, since `method:` is only consulted as a fallback when no
+      #    such method exists. This only applies to `method:`: `resolver_method:`
+      #    redirects which name is checked instead of competing with it, so it
+      #    can't be shadowed by a same-named `def` the way `method:` can.
+      #
+      # @example
+      #   # good
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, resolver: Resolvers::AuthorResolver
+      #   end
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, String, null: true, method: :ghostwriter
+      #   end
+      #
+      #   # bad
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, resolver: Resolvers::AuthorResolver, resolver_method: :fetch_author
+      #   end
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, resolver: Resolvers::AuthorResolver, method: :ghostwriter
+      #   end
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, String, null: true, method: :ghostwriter
+      #
+      #     def author
+      #       object.author
+      #     end
+      #   end
+      #
+      class UselessMethodOption < Base
+        include RuboCop::GraphQL::NodePattern
+
+        RESOLVER_MSG = "Remove `%<option>s:`, it has no effect: `resolver: %<resolver>s` " \
+                       "always takes precedence."
+        DEF_MSG = "Remove `method:`, it has no effect: `def %<field_name>s` on the type " \
+                  "always takes precedence."
+        RESTRICT_ON_SEND = %i[field].freeze
+
+        # @!method resolver_method_pair(node)
+        def_node_search :resolver_method_pair, "(pair (sym :resolver_method) ...)"
+
+        # @!method method_pair(node)
+        def_node_search :method_pair, "(pair (sym :method) ...)"
+
+        def on_send(node)
+          return unless field_definition?(node)
+
+          field = RuboCop::GraphQL::Field.new(node)
+
+          if field.kwargs.resolver
+            register_resolver_offenses(node, field)
+          else
+            register_method_shadowed_by_def_offense(node, field)
+          end
+        end
+
+        private
+
+        def register_resolver_offenses(node, field)
+          resolver_source = field.kwargs.resolver.value.source
+
+          [resolver_method_pair(node).first, method_pair(node).first].compact.each do |pair|
+            message = format(RESOLVER_MSG, option: pair.key.value, resolver: resolver_source)
+            add_offense(pair, message: message)
+          end
+        end
+
+        def register_method_shadowed_by_def_offense(node, field)
+          pair = method_pair(node).first
+          return unless pair
+
+          shadowed_def = field.schema_member.find_method_definition(field.name)
+          return unless shadowed_def
+
+          message = format(DEF_MSG, field_name: field.name)
+          add_offense(pair, message: message)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/graphql.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    # Cops for the `GraphQL` department. The department's cops are
+    # registered for lazy loading and their files are loaded on demand.
+    module GraphQL
+      extend LazyLoader
+
+      register_cop :ArgumentDescription, "#{__dir__}/graphql/argument_description"
+      register_cop :ArgumentName, "#{__dir__}/graphql/argument_name"
+      register_cop :ArgumentUniqueness, "#{__dir__}/graphql/argument_uniqueness"
+      register_cop :ContextWriteInType, "#{__dir__}/graphql/context_write_in_type"
+      register_cop :DefaultForOptionalArgument, "#{__dir__}/graphql/default_for_optional_argument"
+      register_cop :DisallowedTypes, "#{__dir__}/graphql/disallowed_types"
+      register_cop :ExtractInputType, "#{__dir__}/graphql/extract_input_type"
+      register_cop :ExtractType, "#{__dir__}/graphql/extract_type"
+      register_cop :FieldDefinitions, "#{__dir__}/graphql/field_definitions"
+      register_cop :FieldDescription, "#{__dir__}/graphql/field_description"
+      register_cop :FieldHashKey, "#{__dir__}/graphql/field_hash_key"
+      register_cop :FieldMethod, "#{__dir__}/graphql/field_method"
+      register_cop :FieldName, "#{__dir__}/graphql/field_name"
+      register_cop :FieldUniqueness, "#{__dir__}/graphql/field_uniqueness"
+      register_cop :GraphqlName, "#{__dir__}/graphql/graphql_name"
+      register_cop :LegacyDsl, "#{__dir__}/graphql/legacy_dsl"
+      register_cop :MaxComplexitySchema, "#{__dir__}/graphql/max_complexity_schema"
+      register_cop :MaxDepthSchema, "#{__dir__}/graphql/max_depth_schema"
+      register_cop :MethodShadowedByResolverMethod, "#{__dir__}/graphql/method_shadowed_by_resolver_method"
+      register_cop :MultipleFieldDefinitions, "#{__dir__}/graphql/multiple_field_definitions"
+      register_cop :NotAuthorizedNodeType, "#{__dir__}/graphql/not_authorized_node_type"
+      register_cop :NullabilityMismatch, "#{__dir__}/graphql/nullability_mismatch"
+      register_cop :ResolverMethodLength, "#{__dir__}/graphql/resolver_method_length"
+      register_cop :ObjectDescription, "#{__dir__}/graphql/object_description"
+      register_cop :OrderedArguments, "#{__dir__}/graphql/ordered_arguments"
+      register_cop :OrderedFields, "#{__dir__}/graphql/ordered_fields"
+      register_cop :PrepareMethod, "#{__dir__}/graphql/prepare_method"
+      register_cop :UnusedArgument, "#{__dir__}/graphql/unused_argument"
+      register_cop :UnnecessaryArgumentCamelize, "#{__dir__}/graphql/unnecessary_argument_camelize"
+      register_cop :UnnecessaryFieldAlias, "#{__dir__}/graphql/unnecessary_field_alias"
+      register_cop :UnnecessaryFieldCamelize, "#{__dir__}/graphql/unnecessary_field_camelize"
+      register_cop :UselessMethodOption, "#{__dir__}/graphql/useless_method_option"
+    end
+  end
+end

data/lib/rubocop/cop/graphql_cops.rb

@@ -1,29 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "graphql/argument_description"
-require_relative "graphql/argument_name"
-require_relative "graphql/argument_uniqueness"
-require_relative "graphql/context_write_in_type"
-require_relative "graphql/extract_input_type"
-require_relative "graphql/extract_type"
-require_relative "graphql/field_definitions"
-require_relative "graphql/field_description"
-require_relative "graphql/field_hash_key"
-require_relative "graphql/field_method"
-require_relative "graphql/field_name"
-require_relative "graphql/field_uniqueness"
-require_relative "graphql/graphql_name"
-require_relative "graphql/legacy_dsl"
-require_relative "graphql/max_complexity_schema"
-require_relative "graphql/max_depth_schema"
-require_relative "graphql/multiple_field_definitions"
-require_relative "graphql/not_authorized_node_type"
-require_relative "graphql/resolver_method_length"
-require_relative "graphql/object_description"
-require_relative "graphql/ordered_arguments"
-require_relative "graphql/ordered_fields"
-require_relative "graphql/prepare_method"
-require_relative "graphql/unused_argument"
-require_relative "graphql/unnecessary_argument_camelize"
-require_relative "graphql/unnecessary_field_alias"
-require_relative "graphql/unnecessary_field_camelize"
+# @deprecated This file is deprecated. Cops are registered for lazy loading in
+#   `rubocop/cop/graphql`; this file is kept for compatibility with code
+#   that requires it directly.
+require_relative "graphql"

data/lib/rubocop/graphql/argument/kwargs.rb

@@ -36,6 +36,16 @@ module RuboCop
           (pair (sym :camelize) ...)
         PATTERN
 
+        # @!method required_kwarg?(node)
+        def_node_matcher :required_kwarg?, <<~PATTERN
+          (pair (sym :required) ...)
+        PATTERN
+
+        # @!method default_value_kwarg?(node)
+        def_node_matcher :default_value_kwarg?, <<~PATTERN
+          (pair (sym :default_value) ...)
+        PATTERN
+
         def initialize(argument_node)
           @nodes = argument_kwargs(argument_node) || []
         end
@@ -55,6 +65,14 @@ module RuboCop
         def as
           @nodes.find { |kwarg| as_kwarg?(kwarg) }
         end
+
+        def required
+          @nodes.find { |kwarg| required_kwarg?(kwarg) }
+        end
+
+        def default_value
+          @nodes.find { |kwarg| default_value_kwarg?(kwarg) }
+        end
       end
     end
   end

data/lib/rubocop/graphql/argument.rb

@@ -20,6 +20,11 @@ module RuboCop
         (pair (sym :as) (sym $_))
       PATTERN
 
+      # @!method argument_required(node)
+      def_node_matcher :argument_required, <<~PATTERN
+        (pair (sym :required) $_)
+      PATTERN
+
       attr_reader :node
 
       def initialize(node)
@@ -34,6 +39,29 @@ module RuboCop
         @as ||= argument_as(kwargs.as)
       end
 
+      # The keyword this argument is passed as to #resolve and friends. `as:` wins when both
+      # are given, matching graphql-ruby's `kwargs[:as] ||= inferred_arg_name`.
+      def keyword
+        return as if kwargs.as
+        return inferred_keyword if kwargs.loads
+
+        name
+      end
+
+      # `required: false` is the only value that lets graphql-ruby omit the keyword:
+      # `required: :nullable` still demands the argument be present, though it may be null.
+      def optional?
+        required_node = kwargs.required
+        return false unless required_node
+
+        argument_required(required_node)&.false_type? || false
+      end
+
+      # A configured default is always passed, even when the client omits the argument.
+      def default_value?
+        !kwargs.default_value.nil?
+      end
+
       def description
         @description ||= argument_description(@node) || kwargs.description || block.description
       end
@@ -45,6 +73,23 @@ module RuboCop
       def block
         @block ||= Argument::Block.new(@node.parent)
       end
+
+      private
+
+      # Mirrors graphql-ruby: a `loads:` argument named `foo_id` arrives as `foo:`, and one
+      # named `foo_ids` arrives as `foos:`.
+      def inferred_keyword
+        name_as_string = name.to_s
+
+        case name_as_string
+        when /_id$/
+          name_as_string.sub(/_id$/, "").to_sym
+        when /_ids$/
+          name_as_string.sub(/_ids$/, "").sub(/([^s])$/, "\\1s").to_sym
+        else
+          name
+        end
+      end
     end
   end
 end

data/lib/rubocop/graphql/field/kwargs.rb

@@ -21,6 +21,16 @@ module RuboCop
           (pair (sym :resolver) ...)
         PATTERN
 
+        # @!method mutation_kwarg?(node)
+        def_node_matcher :mutation_kwarg?, <<~PATTERN
+          (pair (sym :mutation) ...)
+        PATTERN
+
+        # @!method subscription_kwarg?(node)
+        def_node_matcher :subscription_kwarg?, <<~PATTERN
+          (pair (sym :subscription) ...)
+        PATTERN
+
         # @!method method_kwarg?(node)
         def_node_matcher :method_kwarg?, <<~PATTERN
           (pair (sym :method) ...)
@@ -59,6 +69,20 @@ module RuboCop
           @nodes.find { |kwarg| resolver_kwarg?(kwarg) }
         end
 
+        def mutation
+          @nodes.find { |kwarg| mutation_kwarg?(kwarg) }
+        end
+
+        def subscription
+          @nodes.find { |kwarg| subscription_kwarg?(kwarg) }
+        end
+
+        # graphql-ruby builds the field's resolver class out of any one of these
+        # options, and the field then inherits configuration from that class.
+        def resolver_class
+          resolver || mutation || subscription
+        end
+
         def method
           @nodes.find { |kwarg| method_kwarg?(kwarg) }
         end

data/lib/rubocop/graphql/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module GraphQL
-    VERSION = "1.6.0".freeze
+    VERSION = "1.8.0".freeze
   end
 end

data/lib/rubocop-graphql.rb

@@ -24,4 +24,4 @@ require_relative "rubocop/graphql/field/block"
 require_relative "rubocop/graphql/field/kwargs"
 require_relative "rubocop/graphql/schema_member"
 
-require_relative "rubocop/cop/graphql_cops"
+require_relative "rubocop/cop/graphql"