debian-mirror-gitlab/rubocop/cop/graphql/descriptions.rb

130 lines
4.2 KiB
Ruby
Raw Normal View History

2019-12-04 20:38:33 +05:30
# frozen_string_literal: true
2021-04-17 20:07:23 +05:30
# This cop checks for missing GraphQL descriptions and enforces the description style guide:
# https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#description-style-guide
2019-12-04 20:38:33 +05:30
#
2021-04-17 20:07:23 +05:30
# @examples
2019-12-04 20:38:33 +05:30
#
# # bad
2021-04-17 20:07:23 +05:30
# class AwfulType
2021-10-27 15:23:28 +05:30
# field :some_field, GraphQL::Types::String
2019-12-04 20:38:33 +05:30
# end
#
2021-04-17 20:07:23 +05:30
# class TerribleType
2021-10-27 15:23:28 +05:30
# argument :some_argument, GraphQL::Types::String
2019-12-04 20:38:33 +05:30
# end
#
2021-04-17 20:07:23 +05:30
# class UngoodType
2021-02-22 17:27:13 +05:30
# field :some_argument,
2021-10-27 15:23:28 +05:30
# GraphQL::Types::String,
2021-02-22 17:27:13 +05:30
# description: "A description that does not end in a period"
# end
#
2021-04-17 20:07:23 +05:30
# class BadEnum
# value "some_value"
# end
#
2019-12-04 20:38:33 +05:30
# # good
2021-04-17 20:07:23 +05:30
# class GreatType
2019-12-04 20:38:33 +05:30
# argument :some_field,
2021-10-27 15:23:28 +05:30
# GraphQL::Types::String,
2021-02-22 17:27:13 +05:30
# description: "Well described - a superb description."
2019-12-04 20:38:33 +05:30
#
# field :some_field,
2021-10-27 15:23:28 +05:30
# GraphQL::Types::String,
# description: "Thorough and compelling description."
2019-12-04 20:38:33 +05:30
# end
2021-04-17 20:07:23 +05:30
#
# class GoodEnum
# value "some_value", "Good description."
# end
2019-12-04 20:38:33 +05:30
module RuboCop
module Cop
module Graphql
class Descriptions < RuboCop::Cop::Cop
2021-10-27 15:23:28 +05:30
MSG_STYLE_GUIDE_LINK = 'See the description style guide: https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#description-style-guide'
MSG_NO_DESCRIPTION = "Please add a `description` property. #{MSG_STYLE_GUIDE_LINK}"
MSG_NO_PERIOD = "`description` strings must end with a `.`. #{MSG_STYLE_GUIDE_LINK}"
MSG_BAD_START = "`description` strings should not start with \"A...\" or \"The...\". #{MSG_STYLE_GUIDE_LINK}"
2019-12-04 20:38:33 +05:30
2021-04-17 20:07:23 +05:30
def_node_matcher :graphql_describable?, <<~PATTERN
(send nil? {:field :argument :value} ...)
PATTERN
def_node_matcher :enum?, <<~PATTERN
(send nil? :value ...)
2019-12-04 20:38:33 +05:30
PATTERN
2021-04-29 21:17:54 +05:30
def_node_matcher :resolver_kwarg, <<~PATTERN
(... (hash <(pair (sym :resolver) $_) ...>))
PATTERN
2021-04-17 20:07:23 +05:30
def_node_matcher :description_kwarg, <<~PATTERN
2021-02-22 17:27:13 +05:30
(... (hash <(pair (sym :description) $_) ...>))
2019-12-04 20:38:33 +05:30
PATTERN
2021-04-17 20:07:23 +05:30
def_node_matcher :enum_style_description, <<~PATTERN
(send nil? :value _ $str ...)
PATTERN
2019-12-04 20:38:33 +05:30
def on_send(node)
2021-04-17 20:07:23 +05:30
return unless graphql_describable?(node)
2021-04-29 21:17:54 +05:30
return if resolver_kwarg(node) # Fields may inherit the description from their resolvers.
2021-02-22 17:27:13 +05:30
2021-04-17 20:07:23 +05:30
description = locate_description(node)
2021-02-22 17:27:13 +05:30
return add_offense(node, location: :expression, message: MSG_NO_DESCRIPTION) unless description
add_offense(node, location: :expression, message: MSG_NO_PERIOD) if no_period?(description)
2021-10-27 15:23:28 +05:30
add_offense(node, location: :expression, message: MSG_BAD_START) if bad_start?(description)
2021-02-22 17:27:13 +05:30
end
# Autocorrect missing periods at end of description.
def autocorrect(node)
lambda do |corrector|
2021-04-17 20:07:23 +05:30
description = locate_description(node)
2021-02-22 17:27:13 +05:30
next unless description
corrector.insert_after(before_end_quote(description), '.')
end
end
private
2021-04-17 20:07:23 +05:30
# Fields and arguments define descriptions using a `description` keyword argument.
# Enums may define descriptions this way, or as a second `String` param.
def locate_description(node)
description = description_kwarg(node)
return description unless description.nil? && enum?(node)
enum_style_description(node)
end
2021-02-22 17:27:13 +05:30
def no_period?(description)
2021-10-27 15:23:28 +05:30
string?(description) && !description.value.strip.end_with?('.')
2021-02-22 17:27:13 +05:30
end
2019-12-04 20:38:33 +05:30
2021-10-27 15:23:28 +05:30
def bad_start?(description)
string?(description) && description.value.strip.downcase.start_with?('a ', 'the ')
end
# Returns true if `description` node is a `:str` (as opposed to a `#copy_field_description` call)
def string?(description)
description.type == :str
end
# Returns a `Parser::Source::Range` that ends just before the final `String` delimiter.
2021-02-22 17:27:13 +05:30
def before_end_quote(string)
return string.source_range.adjust(end_pos: -1) unless string.heredoc?
2019-12-04 20:38:33 +05:30
2021-02-22 17:27:13 +05:30
heredoc_source = string.location.heredoc_body.source
adjust = heredoc_source.index(/\s+\Z/) - heredoc_source.length
string.location.heredoc_body.adjust(end_pos: adjust)
2019-12-04 20:38:33 +05:30
end
end
end
end
end