rubocop-yard 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cc400612d09ab5ddf92d7361573854c7338a9601a3c1ed253fee7affb4b56de
-  data.tar.gz: 79b066ad6cf601e2d3eac583333cda1f2f56873dad13d7cc19ee30238e2e9d16
+  metadata.gz: b41b5e256726136d4cd8bfc96fabd2ab0fbc37e69a84c9f29a76456f464cf519
+  data.tar.gz: 678da6e808f7b844e4bd94ab061dbf8176c1aba9c3b279a211bf040f7cba907b
 SHA512:
-  metadata.gz: 03c33163563d342329b62d989beb3dd4635cfa09a26b4ad3b13b7802ebf3c6286d3ebda9a4f28b7453fc42aa9bcfbafa4c6579703b90636e7d1a5ce608262312
-  data.tar.gz: f82f34bf6a182f595669b9c0ef46567b4e86b22d73d17cc672baa297f3dbeb5cdc81aa544abedbf9787fece7aca0632f7e780e811a628d96112e9a095e206f49
+  metadata.gz: c14be7ae06b265ef9396bd3b2c494db30e7165cdcebd74884633053ca24a2007e367dc44bc7e8a17deec4a4c62f83eeabd3ae55bd9065ccc3b89633cf4052aee
+  data.tar.gz: f4fd229b29630192b24036fb59bc145704904a2f9142c26738a71815212fa1bf60a725a7c5b984c63a75c05ac75e31d8a6d55b238cdefce1384a4f69d449c315

data/CHANGELOG.md

@@ -1,7 +1,17 @@
 ## [Unreleased]
 
+## [0.3.0] - 2023-09-16
+
+- Add `YARD/MismatchName`
+    - Check `@param` and `@option` name with method definition
+
+## [0.2.0] - 2023-09-14
+
+- `YARD/TagType`
+    - Check collection tag type syntax
+
 ## [0.1.0] - 2023-09-13
 
-- Add new `YARD/TagTypeSyntax` cop
+- Add new `YARD/TagType` cop
 
 - Initial release

data/README.md

@@ -1,24 +1,46 @@
-# Rubocop::YARD
+# RuboCop::YARD
 
 You can check YARD format in Ruby code comment by RuboCop.
 
+<img src="https://github.com/ksss/rubocop-yard/blob/main/demo.png?raw=true" width=700 />
+
 ## Features
 
-### `YARD/TagTypeSyntax`
+### `YARD/TagType`
 
 Check tag type syntax error.
 
-## Installation
+```
+# @param [Symbol|String]
+#         ^^^^^^^^^^^^^ SyntaxError as YARD tag type
+```
+
+```
+# @param [Hash<Symbol, String>]
+#         ^^^^^^^^^^^^^^^^^^^^ `<Type>` is the collection type syntax. Did you mean `{KeyType => ValueType}` or `Hash{KeyType => ValueType}`
+```
+
+### `YARD/MismatchName`
+
+Check `@param` and `@option` name with method definition.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```rb
+# @param [String] string
+#                 ^^^^^^ `string` is not found in method arguments
+# @option opt bar [String]
+#         ^^^ `opt` is not found in method arguments
+def foo(strings, opts = {})
+```
+
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG --require=false
+    $ bundle add rubocop-yard --require=false
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install rubocop-yard
 
 ## Usage
 
@@ -44,4 +66,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Rubocop::YARD project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ksss/rubocop-yard/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the RuboCop::YARD project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ksss/rubocop-yard/blob/main/CODE_OF_CONDUCT.md).

data/config/default.yml

@@ -1,4 +1,9 @@
-YARD/TagTypeSyntax:
+YARD/TagType:
   Description: 'Check syntax for yard tag type'
   Enabled: true
-  VersionAdded: '0.1.0'
+  VersionAdded: '0.2.0'
+
+YARD/MismatchName
+  Description: 'Check @param and @option name and method parameters'
+  Enabled: true
+  VersionAdded: '0.3.0'

data/lib/rubocop/cop/yard/mismatch_name.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module YARD
+      # @example
+      #   # bad
+      #   # @param [void] baz
+      #   # @option opt aaa [void]
+      #   def foo(bar, opts = {})
+      #   end
+      #
+      #   # good
+      #   # @param [void] bar
+      #   # @param [Array] argsa
+      #   # @option opts aaa [void]
+      #   def foo(bar, opts = {}, *arg)
+      #   end
+      class MismatchName < Base
+        include RangeHelp
+        include DocumentationComment
+
+        def on_def(node)
+          return unless node.arguments?
+
+          preceding_lines = preceding_lines(node)
+          return false unless preceding_comment?(node, preceding_lines.last)
+
+          yard_docstring = preceding_lines.map { |line| line.text.gsub(/\A#\s*/, '') }.join("\n")
+          docstring = ::YARD::DocstringParser.new.parse(yard_docstring)
+          docstring.tags.each do |tag|
+            next unless tag.tag_name == 'param' || tag.tag_name == 'option'
+            next unless node.arguments.none? { |arg_node| tag.name.to_sym == arg_node.name }
+
+            tag_name_regexp = Regexp.new("\\b#{Regexp.escape(tag.name)}\\b")
+            comment = preceding_lines.find { |line| line.text.match?(tag_name_regexp) && line.text.include?("@#{tag.tag_name}") }
+            next unless comment
+
+            start_column = comment.source.index(tag_name_regexp)
+            offense_start = comment.location.column + start_column
+            offense_end = offense_start + tag.name.length - 1
+            range = source_range(processed_source.buffer, comment.location.line, offense_start..offense_end)
+            add_offense(range, message: "`#{tag.name}` is not found in method arguments")
+          end
+        end
+        alias on_defs on_def
+      end
+
+      private
+
+      # @param [void] aaa
+      # @option opts bbb [void]
+      def dummy(aaa, opts = {}, *)
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yard/tag_type.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module YARD
+      # @example
+      #   # bad
+      #   @param [Integer String]
+      #
+      #   # bad
+      #   @param [Hash<Symbol, String>]
+      #
+      #   # bad
+      #   @param [Hash(String)]
+      #
+      #   # bad
+      #   @param [Array{Symbol => String}]
+      #
+      #   # good
+      #   @param [Integer, String]
+      #
+      #   # good
+      #   @param [<String>]
+      #   @param [Array<String>]
+      #   @param [List<String>]
+      #   @param [Array<(String, Fixnum, Hash)>]
+      #
+      #   # good
+      #   @param [(String)]
+      #   @param [Array(String)]
+      #
+      #   # good
+      #   @param [{KeyType => ValueType}]
+      #   @param [Hash{KeyType => ValueType}]
+      class TagType < Base
+        MSG = ''
+        include RangeHelp # @return [void,]
+
+        def on_new_investigation
+          processed_source.comments.each do |comment|
+            next if inline_comment?(comment)
+            next unless include_yard_tag?(comment)
+
+            check(comment)
+          end
+        end
+
+        private
+
+        def check(comment)
+          docstring = comment.text.gsub(/\A#\s*/, '')
+          ::YARD::DocstringParser.new.parse(docstring).tags.each do |tag|
+            next unless tag.types
+
+            ::YARD::Tags::TypesExplainer::Parser.parse(tag.types.join(', ')).each do |types_explainer|
+              check_mismatch_collection_type(comment, types_explainer)
+            end
+          rescue SyntaxError
+            add_offense(tag_range_for_comment(comment), message: 'SyntaxError as YARD tag type')
+          end
+        end
+
+        def check_mismatch_collection_type(comment, types_explainer)
+          case types_explainer
+          when ::YARD::Tags::TypesExplainer::HashCollectionType
+            if types_explainer.name == 'Hash'
+              types_explainer.key_types.each { |t| check_mismatch_collection_type(comment, t) }
+              types_explainer.value_types.each { |t| check_mismatch_collection_type(comment, t) }
+            else
+              did_you_mean = types_explainer.name == 'Array' ? 'Did you mean `<Type>` or `Array<Type>`' : ''
+              message = "`{KeyType => ValueType}` is the hash collection type syntax. #{did_you_mean}"
+              add_offense(tag_range_for_comment(comment), message: message)
+            end
+          when ::YARD::Tags::TypesExplainer::FixedCollectionType
+            if types_explainer.name == 'Hash'
+              message = "`(Type)` is the fixed collection type syntax. Did you mean `{KeyType => ValueType}` or `Hash{KeyType => ValueType}`"
+              add_offense(tag_range_for_comment(comment), message: message)
+            else
+              types_explainer.types.each { |t| check_mismatch_collection_type(comment, t) }
+            end
+          when ::YARD::Tags::TypesExplainer::CollectionType
+            if types_explainer.name == 'Hash'
+              message = "`<Type>` is the collection type syntax. `{KeyType => ValueType}` or `Hash{KeyType => ValueType}` is more good"
+              add_offense(tag_range_for_comment(comment), message: message)
+            else
+              types_explainer.types.each { |t| check_mismatch_collection_type(comment, t) }
+            end
+          end
+        end
+
+        def inline_comment?(comment)
+          !comment_line?(comment.source_range.source_line)
+        end
+
+        def include_yard_tag?(comment)
+          comment.source.match?(/@(?:param|return|option|raise|yieldparam|yieldreturn)\s+\[.*\]/)
+        end
+
+        def tag_range_for_comment(comment)
+          start_column = comment.source.index(/\[/) + 1
+          end_column = comment.source.index(/\]/)
+          offense_start = comment.location.column + start_column
+          offense_end = comment.location.column + end_column
+          source_range(processed_source.buffer, comment.location.line, offense_start..offense_end)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yard_cops.rb

@@ -1,3 +1,5 @@
 # frozen_string_literal: true
+
 require 'yard'
-require_relative 'yard/tag_type_syntax'
+require_relative 'yard/tag_type'
+require_relative 'yard/mismatch_name'

data/lib/rubocop/yard/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module YARD
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/sig/rubocop/yard.rbs

@@ -1,6 +1,17 @@
-module Rubocop
+module RuboCop
   module YARD
     VERSION: String
     # See the writing guide of rbs: https://github.com/ruby/rbs#guides
   end
+  module Cop
+    module YARD
+      class TagType
+        type t = YARD::Tags::TypesExplainer::Type
+               | ::YARD::Tags::TypesExplainer::CollectionType
+               | ::YARD::Tags::TypesExplainer::FixedCollectionType
+               | ::YARD::Tags::TypesExplainer::HashCollectionType
+        private def check_mismatch_collection_type: (untyped comment, t types_explainer) -> void
+      end
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-yard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ksss
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-14 00:00:00.000000000 Z
+date: 2023-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -51,19 +51,20 @@ files:
 - README.md
 - config/default.yml
 - lib/rubocop-yard.rb
-- lib/rubocop/cop/yard/tag_type_syntax.rb
+- lib/rubocop/cop/yard/mismatch_name.rb
+- lib/rubocop/cop/yard/tag_type.rb
 - lib/rubocop/cop/yard_cops.rb
 - lib/rubocop/yard.rb
 - lib/rubocop/yard/inject.rb
 - lib/rubocop/yard/version.rb
 - sig/rubocop/yard.rbs
-homepage: https://ksss.ink/
+homepage: https://github.com/ksss/rubocop-yard
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://ksss.ink/
-  source_code_uri: https://ksss.ink/
-  changelog_uri: https://ksss.ink/
+  homepage_uri: https://github.com/ksss/rubocop-yard
+  source_code_uri: https://github.com/ksss/rubocop-yard
+  changelog_uri: https://github.com/ksss/rubocop-yard
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []

data/lib/rubocop/cop/yard/tag_type_syntax.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module RuboCop
-  module Cop
-    module YARD
-      # @example
-      #   # bad
-      #   @param [Integer String]
-      #
-      #   # bad
-      #   @return [TrueClass|FalseClass]
-      #
-      #   # good
-      #   @param [Integer, String]
-      #
-      #   # good
-      #   @return [Boolean]
-      class TagTypeSyntax < Base
-        MSG = 'SyntaxError as YARD tag type'
-        include RangeHelp # @return [void,]
-
-        def on_new_investigation
-          processed_source.comments.each do |comment|
-            next if inline_comment?(comment)
-            next unless include_yard_tag?(comment)
-
-            check(comment)
-          end
-        end
-
-        private
-
-        def check(comment)
-          docstring = comment.text.gsub(/\A#\s*/, '')
-          ::YARD::DocstringParser.new.parse(docstring).tags.each do |tag|
-            ::YARD::Tags::TypesExplainer::Parser.parse(tag.types.join(', '))
-          rescue SyntaxError
-            add_offense(tag_range(comment))
-          end
-        end
-
-        def inline_comment?(comment)
-          !comment_line?(comment.source_range.source_line)
-        end
-
-        def include_yard_tag?(comment)
-          comment.source.match?(/@(?:param|return)\s+\[.*\]/)
-        end
-
-        def tag_range(comment)
-          start_column = comment.source.index(/\[/) + 1
-          end_column = comment.source.index(/\]/)
-          offense_start = comment.location.column + start_column
-          offense_end = comment.location.column + end_column
-          source_range(processed_source.buffer, comment.location.line, offense_start..offense_end)
-        end
-      end
-    end
-  end
-end