yard-lint 0.2.0

data/lib/yard/lint/validators/tags/option_tags/validator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OptionTags
+          # Validator to check methods with options hash have @option tags
+          class Validator < Base
+            private
+
+            # Runs yard list query to find methods with options parameter but missing @option tags
+            # @param dir [String] dir where the yard db is (or where it should be generated)
+            # @param escaped_file_names [String] files for which we want to get the stats
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard list \
+                --private \
+                --protected \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+              cmd = cmd.gsub('yard list', "yard list --query #{query}")
+
+              shell(cmd)
+            end
+
+            # @return [String] yard query to find methods with options parameter
+            #   but no @option tags
+            def query
+              <<~QUERY
+                '
+                  if object.is_a?(YARD::CodeObjects::MethodObject)
+                      # Check if method has a parameter named "options" or "opts"
+                    has_options_param = object.parameters.any? do |param|
+                      param_name = param[0].to_s.gsub(/[*:]/, '')
+                      ['options', 'opts', 'kwargs'].include?(param_name)
+                      end
+
+                    if has_options_param
+                        # Check if method has any @option tags
+                      option_tags = object.tags(:option)
+
+                      if option_tags.empty?
+                        puts object.file + ':' + object.line.to_s + ': ' + object.title
+                        puts 'missing_option_tags'
+                        end
+                      end
+                    end
+                  false
+                '
+              QUERY
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/option_tags.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # OptionTags validator module
+        module OptionTags
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/order/config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module Order
+          # Configuration for Order validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :order
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'convention',
+              'EnforcedOrder' => %w[
+                param
+                option
+                yield
+                yieldparam
+                yieldreturn
+                return
+                raise
+                see
+                example
+                note
+                todo
+              ]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/order/messages_builder.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module Order
+          # Builds messages for invalid tag order offenses
+          class MessagesBuilder
+            class << self
+              # Build message for invalid tag order
+              # @param offense [Hash] offense data with :method_name and :order keys
+              # @return [String] formatted message
+              def call(offense)
+                expected_order = offense[:order]
+                                 .to_s
+                                 .split(',')
+                                 .map { |tag| "`#{tag}`" }
+                                 .join(', ')
+
+                "The `#{offense[:method_name]}` has yard tags in an invalid order. " \
+                  "Following tags need to be in the presented order: #{expected_order}."
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/order/parser.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module Order
+          # Class used to extract warnings details that are related to yard invalid tags order
+          class Parser < Parsers::Base
+            # Regexp to extract only word and numeric parts of the location line
+            NORMALIZATION_REGEXP = /\w+/
+
+            private_constant :NORMALIZATION_REGEXP
+
+            # @param yard_list [Hash] hash with :result key containing raw yard list results string
+            #   and :tags_order key with expected tags order
+            # @return [Array<Hash>] hashes with details about objects with docs with invalid tags
+            #   order.
+            def call(yard_list)
+              # Return empty array if yard_list is nil or empty
+              return [] if yard_list.nil? || yard_list.empty?
+              return [] if yard_list[:result].nil? || yard_list[:result].empty?
+
+              # Each raw offense result is combined out of two lines:
+              #   - first line contains the issue location
+              #   - second the order in which the tags should be
+              # That's why we split it and then for building the locations hashes we can use the
+              #   UndocumentedMethodArguments parser as the location format is the same for both
+              #   raw inputs
+              base_hash = {}
+
+              yard_list[:result].split("\n").each_slice(2).each do |location, ordering|
+                key = normalize(location)
+
+                if ordering == 'valid'
+                  base_hash[key] = 'valid'
+                else
+                  base_hash[key] ||= [location, ordering]
+                end
+              end
+
+              base_hash.delete_if { |_key, value| value == 'valid' }
+              order = base_hash.values.map(&:last)
+
+              Validators::Documentation::UndocumentedMethodArguments::Parser
+                .new
+                .call(base_hash.values.map(&:first).join("\n"))
+                .each.with_index { |element, index| element[:order] = order[index] }
+            end
+
+            private
+
+            # @param location_line [String] full line with the location. It can be used, when we
+            #   use module_function or other aliases that alter the yard tags order
+            # @return [String] line without special characters
+            def normalize(location_line)
+              location_line
+                .scan(NORMALIZATION_REGEXP)
+                .join
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/order/result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module Order
+          # Result object for tag order validation
+          # Transforms parsed tag order violations into offense objects
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'method'
+            self.offense_name = 'InvalidTagOrder'
+
+            # Build human-readable message for tag order offense
+            # @param offense [Hash] offense data with :method_name and :order keys
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/order/validator.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module Order
+          # Runs a query that will pick all the objects that have docs with tags in an invalid
+          #   order. By invalid we mean, that they are not as defined in the settings.
+          class Validator < Base
+            private
+
+            # Runs yard list query with proper settings on a given dir and files
+            # @param dir [String] dir where the yard db is (or where it should be generated)
+            # @param escaped_file_names [String] files for which we want to get the stats
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard list \
+                --private \
+                --protected \
+                --query #{query} \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+
+              result = shell(cmd)
+              result[:stdout] = { result: result[:stdout], tags_order: tags_order }
+              result
+            end
+
+            # @return [String] multiline yard query that we use to find methods with
+            #   tags that are not in the valid order
+            # @note We need to print things for all of the elements as some of them
+            #   are listed in yard twice (for example module functions), and for the
+            #   second time, yard injects things by itself making it impossible to
+            #   figure out whether the order is ok or now. That's why we print all and those
+            #   that are ok, we mark with 'valid' and if it is reported later as invalid again,
+            #   we know, that it is valid
+            def query
+              <<-QUERY
+            '
+              tags_order = #{query_array(tags_order)}
+              accu = []
+              str = "@"
+              slash = 92.chr
+              regexp = "^"+str+"("+slash+"S+)"
+              doc_tags = object.docstring.all.scan(Regexp.new(regexp)).flatten
+
+              doc_tags.each do |param|
+                accu << param unless accu.last == param
+              end
+
+              tags_order.delete_if { |el| !accu.include?(el) }
+              accu.delete_if { |el| !tags_order.include?(el) }
+
+              tags_orders = tags_order.join.to_i(36)
+              accus = accu.join.to_i(36)
+
+              puts object.file + ":" + object.line.to_s + ": " + object.title
+
+              if accus != tags_orders && !is_alias?
+                puts tags_order.join(",")
+              else
+                puts "valid"
+              end
+
+              false
+            ' \\
+              QUERY
+            end
+
+            # @return [Array<String>] tags order
+            def tags_order
+              config.validator_config('Tags/Order', 'EnforcedOrder')
+            end
+
+            # @param elements [Array<String>] array of elements that we want to convert into
+            #   a string ruby yard query array form
+            # @return [String] array of elements for yard query converted into a string
+            def query_array(elements)
+              "[#{elements.map { |type| "\"#{type}\"" }.join(',')}]"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/order.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # Order validator module
+        module Order
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # Validator for detecting duplicated parameter names in @param tags
+        module DuplicatedParameterName
+          # Configuration for DuplicatedParameterName validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :duplicated_parameter_name
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'error'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name/parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module DuplicatedParameterName
+          # Parser for DuplicatedParameterName warnings
+          class Parser < ::Yard::Lint::Parsers::OneLineBase
+            # Set of regexps for detecting warnings reported by YARD stats
+            self.regexps = {
+              general: /^\[warn\]: @param tag has duplicate parameter name/,
+              message: /\[warn\]: (.*) in file/,
+              location: /in file `(.*)`/,
+              line: /line (\d*)/
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module DuplicatedParameterName
+          # Result object for DuplicatedParameterName validation
+          class Result < Results::Base
+            self.default_severity = 'error'
+            self.offense_type = 'line'
+            self.offense_name = 'DuplicatedParameterName'
+
+            # Build human-readable message for DuplicatedParameterName offense
+            # @param offense [Hash] offense data with :message key
+            # @return [String] formatted message
+            def build_message(offense)
+              offense[:message] || 'DuplicatedParameterName detected'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name/validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module DuplicatedParameterName
+          # Runs YARD stats command to check for duplicatedparametername
+          class Validator < Base
+            private
+
+            # Runs YARD stats command with proper settings on a given dir and files
+            # @param dir [String] dir where we should generate the temp docs
+            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard stats \
+                  #{shell_arguments} \
+                --compact \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # DuplicatedParameterName validator module
+        module DuplicatedParameterName
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_directive_format/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # Validator for detecting invalid directive formats
+        module InvalidDirectiveFormat
+          # Configuration for InvalidDirectiveFormat validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :invalid_directive_format
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'error'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_directive_format/parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module InvalidDirectiveFormat
+          # Parser for InvalidDirectiveFormat warnings
+          class Parser < ::Yard::Lint::Parsers::OneLineBase
+            # Set of regexps for detecting warnings reported by YARD stats
+            self.regexps = {
+              general: /^\[warn\]: Invalid directive format/,
+              message: /\[warn\]: (.*) in file/,
+              location: /in file `(.*)`/,
+              line: /line (\d*)/
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_directive_format/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module InvalidDirectiveFormat
+          # Result object for InvalidDirectiveFormat validation
+          class Result < Results::Base
+            self.default_severity = 'error'
+            self.offense_type = 'line'
+            self.offense_name = 'InvalidDirectiveFormat'
+
+            # Build human-readable message for InvalidDirectiveFormat offense
+            # @param offense [Hash] offense data with :message key
+            # @return [String] formatted message
+            def build_message(offense)
+              offense[:message] || 'InvalidDirectiveFormat detected'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_directive_format/validator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module InvalidDirectiveFormat
+          # Runs YARD stats command to check for invaliddirectiveformat
+          class Validator < Base
+            private
+
+            # Runs YARD stats command with proper settings on a given dir and files
+            # @param dir [String] dir where we should generate the temp docs
+            # @param escaped_file_names [String] files for which we want to run YARD stats
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard stats \
+                  #{shell_arguments} \
+                --compact \
+                -b #{Shellwords.escape(dir)} \
+                  #{escaped_file_names}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_directive_format.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # InvalidDirectiveFormat validator module
+        module InvalidDirectiveFormat
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_tag_format/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # Validator for detecting invalid tag formats
+        module InvalidTagFormat
+          # Configuration for InvalidTagFormat validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :invalid_tag_format
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'error'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_tag_format/parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module InvalidTagFormat
+          # Parser for InvalidTagFormat warnings
+          class Parser < ::Yard::Lint::Parsers::OneLineBase
+            # Set of regexps for detecting warnings reported by YARD stats
+            self.regexps = {
+              general: /^\[warn\]: Invalid tag format/,
+              message: /\[warn\]: (.*) in file/,
+              location: /in file `(.*)`/,
+              line: /line (\d*)/
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/invalid_tag_format/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module InvalidTagFormat
+          # Result object for InvalidTagFormat validation
+          class Result < Results::Base
+            self.default_severity = 'error'
+            self.offense_type = 'line'
+            self.offense_name = 'InvalidTagFormat'
+
+            # Build human-readable message for InvalidTagFormat offense
+            # @param offense [Hash] offense data with :message key
+            # @return [String] formatted message
+            def build_message(offense)
+              offense[:message] || 'InvalidTagFormat detected'
+            end
+          end
+        end
+      end
+    end
+  end
+end