rubocop-graphql 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ff189b7091fa3e71688dcb2a2ef36b15edbe018796943ef3b3dfee85b1c32f8
-  data.tar.gz: 2d2ffa4470e74e3ae9d90fac4fc85a173db7d95eb2d5a6bfd844759fad59c514
+  metadata.gz: f7108c819a363b06725b9de204f6e1eb26a19c0e022d07a51f7cac3570ccc041
+  data.tar.gz: 5b5b231155cf6ac19e58df7ab0ded5060517f0a59ed5b3bcef77db04adf9355a
 SHA512:
-  metadata.gz: 1651ab77310a0146fe7847161a6a18afa0c5d83148eca7701def628f66d31b24cfa4760fe94843d9c10db45ca43aa7b7c0d0539901c71be89bf5b3299242caca
-  data.tar.gz: 8b2d079c283776eaac5fdd151fc589d9f29e7afe7826657f23f577a98882166f1a31c57727a1f8dca90a49c058b9def85d3026be5fa483b11227fc81006be50f
+  metadata.gz: 2bd922b4a7234a4ca1315dc42fd6b3adf7fff850bce9ec71abf41df175fd56889cd76be254dcdb4bbec09615dc85a8317a87884778fc62797ab991f63eee04bf
+  data.tar.gz: 282acda7b0c3f54e51a7e77245964e55d3d9d0847009490bfa096959cb49d5de72536e0e49b94f148dbfe1c72c40877494ce8edc9d5187c9b8eacdcf33be6129

data/config/default.yml

@@ -28,6 +28,19 @@ GraphQL/ContextWriteInType:
   Include:
     - '**/graphql/types/**/*'
 
+GraphQL/DefaultForOptionalArgument:
+  Enabled: true
+  VersionAdded: '1.8.0'
+  Description: 'Optional arguments should have a default value in the resolver signature'
+
+GraphQL/DisallowedTypes:
+  Enabled: false
+  VersionAdded: '1.8.0'
+  Description: 'Flags field and argument types the project has decided not to expose'
+  # Type name => the message explaining what to use instead. Nothing is disallowed
+  # until this is configured, so the cop is inert out of the box.
+  Types: {}
+
 GraphQL/ExtractInputType:
   Enabled: true
   VersionAdded: '0.2.0'
@@ -119,7 +132,7 @@ GraphQL/MaxDepthSchema:
 
 GraphQL/MethodShadowedByResolverMethod:
   Enabled: true
-  VersionAdded: '<<next>>'
+  VersionAdded: '1.8.0'
   Description: 'Checks for method definitions shadowed by the field''s effective resolver_method'
 
 GraphQL/MultipleFieldDefinitions:
@@ -135,6 +148,11 @@ GraphQL/NotAuthorizedNodeType:
     - '**/graphql/types/**/*'
   SafeBaseClasses: []
 
+GraphQL/NullabilityMismatch:
+  Enabled: true
+  VersionAdded: '1.8.0'
+  Description: 'Detects a non-null field whose Sorbet resolver signature returns a nilable type'
+
 GraphQL/ResolverMethodLength:
   Enabled: true
   VersionAdded: '0.1.0'
@@ -148,6 +166,13 @@ GraphQL/ObjectDescription:
   Enabled: true
   VersionAdded: '0.3.0'
   Description: 'Ensures all types have a description'
+  # Skip the root operation types (Query, Mutation, Subscription), which are
+  # usually left undescribed. Set to false to require a description on them too.
+  IgnoreRootTypes: true
+  # Superclass (or included module) names to treat as GraphQL bases, on top of the
+  # conventional ones. Use when your base types are named unconventionally, e.g.
+  # `class Types::UserType < ApplicationType`.
+  AdditionalTypeBases: []
   Exclude:
     - "spec/**/*"
     - "test/**/*"
@@ -190,5 +215,5 @@ GraphQL/UnnecessaryFieldCamelize:
 
 GraphQL/UselessMethodOption:
   Enabled: true
-  VersionAdded: '<<next>>'
+  VersionAdded: '1.8.0'
   Description: 'Checks for resolver_method:/method: made ineffective by resolver:, or method: shadowed by a same-named def'

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module GraphQL
+      # Optional arguments should have a default value in the resolver signature.
+      #
+      # When the client omits an argument declared `required: false`, graphql-ruby leaves it
+      # out of the keyword arguments entirely, so a required keyword raises
+      # `ArgumentError: missing keyword`. Giving the keyword a default value is what makes the
+      # argument actually optional at runtime.
+      #
+      # Arguments declared with a `default_value:` are always passed, so they are not reported.
+      # Neither is `required: :nullable`, which still demands the argument be present.
+      #
+      # Both class-level arguments (checked against `#resolve` and `#authorized?`) and
+      # arguments defined inside a field block (checked against that field's resolver method)
+      # are covered.
+      #
+      # @example
+      #   # bad
+      #
+      #   class SomeResolver < Resolvers::Base
+      #     argument :name, String, required: false
+      #
+      #     def resolve(name:); end
+      #   end
+      #
+      #   # good
+      #
+      #   class SomeResolver < Resolvers::Base
+      #     argument :name, String, required: false
+      #
+      #     def resolve(name: nil); end
+      #   end
+      #
+      #   # good - a default value means the keyword is always passed
+      #
+      #   class SomeResolver < Resolvers::Base
+      #     argument :name, String, required: false, default_value: "anonymous"
+      #
+      #     def resolve(name:); end
+      #   end
+      #
+      #   # bad
+      #
+      #   class UserType < BaseObject
+      #     field :posts, [PostType], null: false do
+      #       argument :limit, Integer, required: false
+      #     end
+      #
+      #     def posts(limit:); end
+      #   end
+      #
+      #   # good
+      #
+      #   class UserType < BaseObject
+      #     field :posts, [PostType], null: false do
+      #       argument :limit, Integer, required: false
+      #     end
+      #
+      #     def posts(limit: 10); end
+      #   end
+      #
+      class DefaultForOptionalArgument < Base
+        MSG = "Optional argument `%<keyword>s` has no default value in `%<method>s`, so " \
+              "omitting it raises ArgumentError."
+
+        RESOLVER_METHODS = %i[resolve authorized?].freeze
+
+        def on_class(node)
+          body = node.body
+          return unless body
+
+          defs = definitions_in(node)
+          return if defs.empty?
+
+          check_class_arguments(node, defs)
+          check_field_arguments(node, defs)
+        end
+
+        private
+
+        def check_class_arguments(class_node, defs)
+          keywords = optional_keywords(class_arguments(class_node))
+          return if keywords.empty?
+
+          RESOLVER_METHODS.each do |method_name|
+            check_signature(defs[method_name], keywords)
+          end
+        end
+
+        def check_field_arguments(class_node, defs)
+          field_blocks(class_node).each do |block_node|
+            field = RuboCop::GraphQL::Field.new(block_node.send_node)
+            next if field.kwargs.resolver
+
+            keywords = optional_keywords(block_arguments(block_node))
+            next if keywords.empty?
+
+            check_signature(defs[field.resolver_method_name.to_sym], keywords)
+          end
+        end
+
+        def check_signature(def_node, keywords)
+          return unless def_node
+
+          def_node.arguments.each do |arg_node|
+            next unless arg_node.kwarg_type?
+            next unless keywords.include?(arg_node.node_parts[0])
+
+            add_offense(
+              arg_node,
+              message: format(MSG, keyword: arg_node.node_parts[0], method: def_node.method_name)
+            )
+          end
+        end
+
+        # Keywords of arguments that graphql-ruby may leave out of the resolver call.
+        def optional_keywords(argument_nodes)
+          argument_nodes.filter_map do |argument_node|
+            argument = RuboCop::GraphQL::Argument.new(argument_node)
+            argument.keyword if argument.optional? && !argument.default_value?
+          end.to_set
+        end
+
+        # `def`s owned by this class, keyed by name. A nested class gets its own `on_class`.
+        def definitions_in(class_node)
+          each_in_scope(class_node.body, :def).each_with_object({}) do |def_node, defs|
+            defs[def_node.method_name] ||= def_node
+          end
+        end
+
+        # Class-level `argument` calls: the walk stops at blocks, so field-block arguments
+        # (handled separately, against a different method) are not picked up here.
+        def class_arguments(class_node)
+          each_in_scope(class_node.body, :send, stop_at_block: true).select do |send_node|
+            argument_declaration?(send_node)
+          end
+        end
+
+        def block_arguments(block_node)
+          body = block_node.body
+          return [] unless body
+
+          each_in_scope(body, :send).select { |send_node| argument_declaration?(send_node) }
+        end
+
+        def field_blocks(class_node)
+          each_in_scope(class_node.body, :block).select do |block_node|
+            field_declaration?(block_node.send_node)
+          end
+        end
+
+        # Collects nodes of `type` without descending into a nested class or module body.
+        # With `stop_at_block`, a block contributes only the call that opens it, so a nested
+        # `field ... do ... end` keeps its own arguments out of the enclosing scope.
+        def each_in_scope(node, type, stop_at_block: false, found: [])
+          found << node if node.type == type
+          return found if node.type?(:class, :module, :sclass)
+
+          children =
+            if stop_at_block && node.type?(:any_block)
+              [node.send_node]
+            else
+              node.each_child_node
+            end
+
+          children.each do |child|
+            each_in_scope(child, type, stop_at_block: stop_at_block, found: found)
+          end
+          found
+        end
+
+        # @!method argument_declaration?(node)
+        def_node_matcher :argument_declaration?, <<~PATTERN
+          (send nil? :argument (:sym _) ...)
+        PATTERN
+
+        # @!method field_declaration?(node)
+        def_node_matcher :field_declaration?, <<~PATTERN
+          (send nil? :field (:sym _) ...)
+        PATTERN
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module GraphQL
+      # Flags field and argument types the project has decided not to expose, with a message
+      # explaining what to use instead.
+      #
+      # Every schema accumulates types that are still resolvable but shouldn't be reached for
+      # in new code: a scalar kept alive only for backwards compatibility, a type that predates
+      # a better one, or a builtin whose semantics don't fit the domain -- `Float` for money,
+      # say, where the serialization loses precision. The convention is usually documented and
+      # then re-litigated in review; this makes it fail the build instead.
+      #
+      # Nothing is disallowed by default: the cop is inert until `Types` is configured.
+      #
+      # A configured name matches the written constant exactly, or as a trailing segment of it,
+      # so `Float` covers `Float`, `Types::Float` and `GraphQL::Types::Float`. Configure
+      # `GraphQL::Types::Float` instead to match only the fully qualified form.
+      #
+      # List types are unwrapped, so `[Float]` and `[Float, null: true]` are flagged too, and
+      # both the positional type and the `type:` keyword are checked.
+      #
+      # @example Types: {'Float' => 'Use Types::Decimal, which serializes as a string.'}
+      #   # bad
+      #   field :amount, Float, null: false
+      #   argument :amount, Float, required: true
+      #   field :amounts, [Float], null: false
+      #   field :amount, type: Float, null: false
+      #
+      #   # good
+      #   field :amount, Types::Decimal, null: false
+      #   argument :amount, Types::Decimal, required: true
+      #
+      # @example Types: {'Types::LegacyDate' => 'Use GraphQL::Types::ISO8601Date.'}
+      #   # bad
+      #   field :starts_on, Types::LegacyDate, null: false
+      #
+      #   # good
+      #   field :starts_on, GraphQL::Types::ISO8601Date, null: false
+      #
+      class DisallowedTypes < Base
+        MSG = "`%<type>s` is not allowed as a field or argument type."
+        MSG_WITH_REASON = "`%<type>s` is not allowed as a field or argument type. %<reason>s"
+
+        RESTRICT_ON_SEND = %i[field argument].freeze
+
+        def on_send(node)
+          return if disallowed_types.empty?
+          return unless type_declaration?(node)
+
+          each_type_const(node) do |const_node|
+            configured_name = disallowed_name_for(const_node)
+            next unless configured_name
+
+            add_offense(const_node, message: message_for(configured_name))
+          end
+        end
+
+        private
+
+        def disallowed_types
+          @disallowed_types ||= (cop_config["Types"] || {}).transform_keys(&:to_s)
+        end
+
+        def message_for(configured_name)
+          reason = disallowed_types[configured_name].to_s.strip
+
+          if reason.empty?
+            format(MSG, type: configured_name)
+          else
+            format(MSG_WITH_REASON, type: configured_name, reason: reason)
+          end
+        end
+
+        def disallowed_name_for(const_node)
+          written_name = const_node.const_name
+
+          disallowed_types.keys.find do |configured_name|
+            written_name == configured_name || written_name.end_with?("::#{configured_name}")
+          end
+        end
+
+        # Yields the constants a `field`/`argument` call names as its type: the positional type
+        # and the `type:` keyword, each unwrapped through any list nesting.
+        def each_type_const(send_node, &block)
+          each_const_in(send_node.arguments[1], &block)
+          each_const_in(type_kwarg(send_node), &block)
+        end
+
+        def each_const_in(node, &block)
+          return unless node
+
+          case node.type
+          when :const then yield node
+          when :array then node.children.each { |child| each_const_in(child, &block) }
+          end
+        end
+
+        # An explicit receiver means this is some other `field`/`argument` method, not the DSL.
+        #
+        # @!method type_declaration?(node)
+        def_node_matcher :type_declaration?, <<~PATTERN
+          (send nil? {:field :argument} ...)
+        PATTERN
+
+        # @!method type_kwarg(node)
+        def_node_matcher :type_kwarg, <<~PATTERN
+          (send nil? {:field :argument} ... (hash <(pair (sym :type) $_) ...>))
+        PATTERN
+      end
+    end
+  end
+end

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

@@ -18,6 +18,16 @@ module RuboCop
       #     field :name, String, null: true
       #   end
       #
+      # Fields built from a resolver, mutation or subscription class are not
+      # flagged: graphql-ruby takes their description from that class.
+      #
+      # @example
+      #   # good
+      #
+      #   class UserType < BaseType
+      #     field :posts, resolver: PostsResolver
+      #   end
+      #
       class FieldDescription < Base
         include RuboCop::GraphQL::NodePattern
 
@@ -28,6 +38,7 @@ module RuboCop
           return unless field_definition?(node)
 
           field = RuboCop::GraphQL::Field.new(node)
+          return if field.kwargs.resolver_class
 
           add_offense(node) unless field.description
         end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module GraphQL
+      # A non-null field should not have a resolver whose Sorbet signature returns a nilable
+      # type. The two disagree: the schema promises a value, the signature admits `nil`, and
+      # graphql-ruby raises an invalid-null error for every object that resolves to `nil`.
+      #
+      # Sorbet cannot catch this, because the field declaration is not part of the signature.
+      # Only the crashing direction is reported: a nullable field with a non-nilable resolver
+      # is merely imprecise, not broken.
+      #
+      # Codebases without Sorbet signatures never trigger this cop.
+      #
+      # @example
+      #   # bad
+      #
+      #   class UserType < BaseObject
+      #     field :name, String, null: false
+      #
+      #     sig { override.returns(T.nilable(String)) }
+      #     def name
+      #       object.name
+      #     end
+      #   end
+      #
+      #   # good - the schema admits what the resolver may return
+      #
+      #   class UserType < BaseObject
+      #     field :name, String, null: true
+      #
+      #     sig { override.returns(T.nilable(String)) }
+      #     def name
+      #       object.name
+      #     end
+      #   end
+      #
+      #   # good - the resolver guarantees what the schema promises
+      #
+      #   class UserType < BaseObject
+      #     field :name, String, null: false
+      #
+      #     sig { override.returns(String) }
+      #     def name
+      #       object.name || "anonymous"
+      #     end
+      #   end
+      #
+      class NullabilityMismatch < Base
+        include RuboCop::GraphQL::Sorbet
+
+        MSG = "Field `%<field>s` is `null: false` but its resolver signature returns a " \
+              "nilable type, so a nil resolves to an invalid null error."
+
+        def on_class(node)
+          non_null_fields = collect_non_null_fields(node)
+          return if non_null_fields.empty?
+
+          node.each_descendant(:def) do |def_node|
+            next unless owned_by?(def_node, node)
+
+            field_node = non_null_fields[def_node.method_name]
+            next unless field_node && nilable_signature?(def_node)
+
+            field_name = RuboCop::GraphQL::Field.new(field_node).name
+            add_offense(field_node, message: format(MSG, field: field_name))
+          end
+        end
+        alias on_module on_class
+
+        private
+
+        # Non-null fields owned by this type, keyed by the method that resolves them. Fields
+        # handed off to a `resolver:` class are resolved elsewhere, so they are skipped.
+        def collect_non_null_fields(node)
+          fields = {}
+
+          node.each_descendant(:send) do |send_node|
+            next unless non_null_field?(send_node) && owned_by?(send_node, node)
+
+            field = RuboCop::GraphQL::Field.new(send_node)
+            next if field.kwargs.resolver
+
+            fields[field.resolver_method_name.to_sym] ||= send_node
+          end
+
+          fields
+        end
+
+        def nilable_signature?(def_node)
+          signature = sorbet_signature_for(def_node)
+          return false unless signature
+
+          signature.each_descendant(:send).any? do |send_node|
+            send_node.method?(:returns) && nilable_type?(send_node.first_argument)
+          end
+        end
+
+        # Only the outermost type counts. `T::Array[T.nilable(String)]` is a non-null list of
+        # nullable items, which pairs correctly with a `null: false` field.
+        def nilable_type?(node)
+          return false unless node
+          return true if t_nilable?(node)
+
+          Array(t_any_types(node)).any? { |type| nil_class?(type) }
+        end
+
+        # True when `node`'s nearest enclosing class or module is `owner`, so that a nested
+        # type's fields and methods are not attributed to the one around it.
+        def owned_by?(node, owner)
+          node.each_ancestor(:class, :module).first == owner
+        end
+
+        # @!method non_null_field?(node)
+        def_node_matcher :non_null_field?, <<~PATTERN
+          (send nil? :field (sym _) ... (hash <(pair (sym :null) (false)) ...>))
+        PATTERN
+
+        # @!method t_nilable?(node)
+        def_node_matcher :t_nilable?, <<~PATTERN
+          (send (const {nil? cbase} :T) :nilable ...)
+        PATTERN
+
+        # @!method t_any_types(node)
+        def_node_matcher :t_any_types, <<~PATTERN
+          (send (const {nil? cbase} :T) :any $...)
+        PATTERN
+
+        # @!method nil_class?(node)
+        def_node_matcher :nil_class?, <<~PATTERN
+          (const {nil? cbase} :NilClass)
+        PATTERN
+      end
+    end
+  end
+end

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/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.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,31 +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/method_shadowed_by_resolver_method"
-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"
-require_relative "graphql/useless_method_option"
+# @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.7.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"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-graphql
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Dmitry Tsepelev
 bindir: bin
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -71,7 +71,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.72.1
+        version: '1.89'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -81,7 +81,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.72.1
+        version: '1.89'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -97,10 +97,13 @@ files:
 - config/default.yml
 - lib/refinements/underscore_string.rb
 - lib/rubocop-graphql.rb
+- lib/rubocop/cop/graphql.rb
 - lib/rubocop/cop/graphql/argument_description.rb
 - lib/rubocop/cop/graphql/argument_name.rb
 - lib/rubocop/cop/graphql/argument_uniqueness.rb
 - lib/rubocop/cop/graphql/context_write_in_type.rb
+- lib/rubocop/cop/graphql/default_for_optional_argument.rb
+- lib/rubocop/cop/graphql/disallowed_types.rb
 - lib/rubocop/cop/graphql/extract_input_type.rb
 - lib/rubocop/cop/graphql/extract_type.rb
 - lib/rubocop/cop/graphql/field_definitions.rb
@@ -116,6 +119,7 @@ files:
 - lib/rubocop/cop/graphql/method_shadowed_by_resolver_method.rb
 - lib/rubocop/cop/graphql/multiple_field_definitions.rb
 - lib/rubocop/cop/graphql/not_authorized_node_type.rb
+- lib/rubocop/cop/graphql/nullability_mismatch.rb
 - lib/rubocop/cop/graphql/object_description.rb
 - lib/rubocop/cop/graphql/ordered_arguments.rb
 - lib/rubocop/cop/graphql/ordered_fields.rb