rubocop-graphql 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a19f13dab5d269042eab2a3dfb06746f70d78ebd512e4656cb384d1e2f0a77c
-  data.tar.gz: e67b156307473082e114b860097ca80d1ba23c9987359ad6ee6c56d7641552d3
+  metadata.gz: f7108c819a363b06725b9de204f6e1eb26a19c0e022d07a51f7cac3570ccc041
+  data.tar.gz: 5b5b231155cf6ac19e58df7ab0ded5060517f0a59ed5b3bcef77db04adf9355a
 SHA512:
-  metadata.gz: 412c2b4547281975d17d77cbff5a40e737d49a597747bdd85ccba722dfac63c35f30e33027bb252c3ad6939d43348609ac291baeb37f7f4c2f187e4e427635f6
-  data.tar.gz: '080b77b04d717024d92a79ec83635b1f43e56412240a6a4d6068bec5060a65c5365438158742d579c1fe9d4fd77636ddd19d02055b0003a9d6083c6da15d5d59'
+  metadata.gz: 2bd922b4a7234a4ca1315dc42fd6b3adf7fff850bce9ec71abf41df175fd56889cd76be254dcdb4bbec09615dc85a8317a87884778fc62797ab991f63eee04bf
+  data.tar.gz: 282acda7b0c3f54e51a7e77245964e55d3d9d0847009490bfa096959cb49d5de72536e0e49b94f148dbfe1c72c40877494ce8edc9d5187c9b8eacdcf33be6129

data/README.md

@@ -2,7 +2,10 @@
 
 [Rubocop](https://github.com/rubocop-hq/rubocop) extension for enforcing [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) best practices.
 
-You can support my open–source work [here](https://boosty.to/dmitry_tsepelev).
+## Professional Support
+
+Need help with your GraphQL API architecture, schema design, or performance?
+I'm available for consulting — [get in touch](https://dmitrytsepelev.dev/consulting).
 
 ## Installation
 

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'
@@ -117,6 +130,11 @@ GraphQL/MaxDepthSchema:
   Include:
     - '**/graphql/**/*_schema.rb'
 
+GraphQL/MethodShadowedByResolverMethod:
+  Enabled: true
+  VersionAdded: '1.8.0'
+  Description: 'Checks for method definitions shadowed by the field''s effective resolver_method'
+
 GraphQL/MultipleFieldDefinitions:
   Enabled: true
   VersionAdded: '0.15.0'
@@ -130,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'
@@ -143,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/**/*"
@@ -182,3 +212,8 @@ GraphQL/UnnecessaryFieldCamelize:
   Enabled: true
   VersionAdded: '0.18.0'
   Description: "Camelize isn't necessary if the field name doesn't contain underscores"
+
+GraphQL/UselessMethodOption:
+  Enabled: true
+  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/method_shadowed_by_resolver_method.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module GraphQL
+      #  This cop detects method definitions that are never called because
+      #  the field's effective `resolver_method` points somewhere else.
+      #
+      #  graphql-ruby only ever calls a single method on the type instance:
+      #  the field's `resolver_method` (which is the resolver class's own
+      #  method when `resolver:` is set, the explicit `resolver_method:`
+      #  value when given, or the field name otherwise). Any other
+      #  same-named method left on the type is unreachable:
+      #
+      #  - When `resolver:` is set, the resolver class handles resolution
+      #    entirely, so neither the field name, `resolver_method:`, nor
+      #    `method:` (if also given) is ever dispatched to a method on the type.
+      #  - When only `resolver_method:` is set, that name is the one
+      #    actually called -- a leftover method matching the plain field
+      #    name is never reached.
+      #
+      # @example
+      #   # good
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, resolver: Resolvers::AuthorResolver
+      #   end
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, String, null: true, resolver_method: :fetch_author
+      #
+      #     def fetch_author
+      #       object.author
+      #     end
+      #   end
+      #
+      #   # bad
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, resolver: Resolvers::AuthorResolver
+      #
+      #     def author
+      #       object.author
+      #     end
+      #   end
+      #
+      #   class Types::PostType < Types::BaseObject
+      #     field :author, String, null: true, resolver_method: :fetch_author
+      #
+      #     def author
+      #       object.author
+      #     end
+      #
+      #     def fetch_author
+      #       object.author
+      #     end
+      #   end
+      #
+      class MethodShadowedByResolverMethod < Base
+        include RuboCop::GraphQL::NodePattern
+
+        RESOLVER_MSG = "Remove this method, it is never called: `resolver: %<resolver>s` " \
+                       "resolves this field instead."
+        RESOLVER_METHOD_MSG = "Remove this method, it is never called: " \
+                              "`resolver_method: :%<resolver_method>s` is called instead."
+        RESTRICT_ON_SEND = %i[field].freeze
+
+        def on_send(node)
+          return unless field_definition?(node)
+
+          field = RuboCop::GraphQL::Field.new(node)
+
+          if field.kwargs.resolver
+            register_resolver_offenses(field)
+          else
+            register_resolver_method_offense(field)
+          end
+        end
+
+        private
+
+        # Neither `resolver_method:` nor `method:` has any effect once `resolver:` is
+        # set (graphql-ruby always calls the resolver class's own resolver_method), so
+        # a method matching the field's own name, an explicit `resolver_method:`, or
+        # an explicit `method:` is equally unreachable.
+        def register_resolver_offenses(field)
+          resolver_source = field.kwargs.resolver.value.source
+          message = format(RESOLVER_MSG, resolver: resolver_source)
+
+          candidate_names = [
+            field.name, field.kwargs.resolver_method_name, method_kwarg_name(field)
+          ].compact.uniq
+          candidate_names.each do |method_name|
+            shadowed_method = field.schema_member.find_method_definition(method_name)
+            add_offense(shadowed_method.loc.name, message: message) if shadowed_method
+          end
+        end
+
+        # The `resolver_method:`-named method is the one actually called; only a
+        # leftover method matching the plain field name is dead.
+        def register_resolver_method_offense(field)
+          resolver_method_kwarg = field.kwargs.resolver_method_name
+          return unless resolver_method_kwarg && resolver_method_kwarg != field.name
+
+          shadowed_method = field.schema_member.find_method_definition(field.name)
+          return unless shadowed_method
+
+          message = format(RESOLVER_METHOD_MSG, resolver_method: resolver_method_kwarg)
+          add_offense(shadowed_method.loc.name, message: message)
+        end
+
+        def method_kwarg_name(field)
+          pair = field.kwargs.method
+          return nil unless pair
+
+          value_node = pair.value
+          value_node.value if value_node.sym_type?
+        end
+      end
+    end
+  end
+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