yard-lint 0.2.0

data/lib/yard/lint/validators/documentation/undocumented_boolean_methods/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedBooleanMethods
+          # Configuration for UndocumentedBooleanMethods validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :undocumented_boolean_methods
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_boolean_methods/parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Documentation validators - check for missing or incomplete documentation
+      module Documentation
+        module UndocumentedBooleanMethods
+          # Class used to extract details about undocumented boolean methods
+          # @example
+          #   Platform::Analysis::Authors#valid?
+          class Parser < Parsers::Base
+            # Regex to extract location and method name from yard list output
+            LOCATION_REGEX = /^(.+)#(.+)$|^(.+)\.(.+)$/
+
+            # @param yard_list [String] raw yard list results string
+            # @return [Array<Hash>] Array with undocumented boolean methods details
+            def call(yard_list)
+              yard_list
+                .split("\n")
+                .reject(&:empty?)
+                .filter_map do |line|
+                  match_data = line.match(LOCATION_REGEX)
+                  next unless match_data
+
+                  # Handle both instance (#) and class (.) methods
+                  location = match_data[1] || match_data[3]
+                  method_name = match_data[2] || match_data[4]
+
+                  {
+                    location: location,
+                    element: "#{location}##{method_name}",
+                    method_name: method_name,
+                    line: 0 # YARD list doesn't provide line numbers
+                  }
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_boolean_methods/result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedBooleanMethods
+          # Result object for undocumented boolean methods validation
+          # Reuses UndocumentedObjects::MessagesBuilder
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'UndocumentedObject'
+
+            # Build human-readable message for undocumented boolean method offense
+            # @param offense [Hash] offense data
+            # @return [String] formatted message
+            def build_message(offense)
+              UndocumentedObjects::MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_boolean_methods/validator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedBooleanMethods
+          # Runs a query that will pick all the boolean methods (ending with ?) that
+          # do not have a return type or return description documented
+          class Validator < Base
+            # Query to find all the boolean methods without proper return documentation
+            QUERY = <<~QUERY.tr("\n", ' ')
+              '
+                type == :method &&
+                !is_alias? &&
+                is_explicit? &&
+                name.to_s.end_with?("?") &&
+                (tag("return").nil? || tag("return").text.to_s.strip.empty?)
+              '
+            QUERY
+
+            private_constant :QUERY
+
+            private
+
+            # Runs yard list query 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 get the stats
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard list \
+                  #{shell_arguments} \
+                --query #{QUERY} \
+                -q \
+                -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/documentation/undocumented_boolean_methods.rb

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

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedMethodArguments
+          # Configuration for UndocumentedMethodArguments validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :undocumented_method_arguments
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/messages_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedMethodArguments
+          # Builds messages for undocumented method arguments offenses
+          class MessagesBuilder
+            class << self
+              # Build message for undocumented method arguments
+              # @param offense [Hash] offense data with :method_name key
+              # @return [String] formatted message
+              def call(offense)
+                "The `#{offense[:method_name]}` method is missing documentation " \
+                  'for some of the arguments.'
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/parser.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedMethodArguments
+          # Class used to extract details about methods with undocumented arguments
+          # @example
+          #   /path/to/file.rb:10: Platform::Analysis::Authors#initialize
+          class Parser < Parsers::Base
+            # Regex to extract file, line, and method name from yard list output
+            # Format: /path/to/file.rb:10: ClassName#method_name
+            LOCATION_REGEX = /^(.+):(\d+):\s+(.+)[#.](.+)$/
+
+            # @param yard_list [String] raw yard list results string
+            # @return [Array<Hash>] Array with undocumented method arguments details
+            def call(yard_list)
+              yard_list
+                .split("\n")
+                .reject(&:empty?)
+                .filter_map do |line|
+                  match_data = line.match(LOCATION_REGEX)
+                  next unless match_data
+
+                  # Extract: file path, line number, class name, method name
+                  file_path = match_data[1]
+                  line_number = match_data[2].to_i
+                  class_name = match_data[3]
+                  method_name = match_data[4]
+
+                  {
+                    location: file_path,
+                    method_name: method_name,
+                    line: line_number,
+                    class_name: class_name
+                  }
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedMethodArguments
+          # Result object for undocumented method arguments validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'method'
+            self.offense_name = 'UndocumentedMethodArgument'
+
+            # Build human-readable message for undocumented method argument offense
+            # @param offense [Hash] offense data
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/validator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedMethodArguments
+          # Runs yard list to check for missing args docs on methods that were documented
+          class Validator < Base
+            # Options that stats supports but not list
+            UNWANTED_OPTIONS = %w[
+              --list-undoc
+            ].freeze
+
+            # Query to find all the documented methods that have some undocumented
+            # arguments
+            QUERY = <<~QUERY.tr("\n", ' ')
+              '
+                type == :method &&
+                !is_alias? &&
+                is_explicit? &&
+                (parameters.size > @@param.size)
+              '
+            QUERY
+
+            private_constant :UNWANTED_OPTIONS, :QUERY
+
+            private
+
+            # Runs yard list query 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 get the stats
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              shell_args = shell_arguments
+              UNWANTED_OPTIONS.each { |opt| shell_args.gsub!(opt, '') }
+
+              cmd = <<~CMD
+                yard list \
+                  #{shell_args} \
+                --query #{QUERY} \
+                -q \
+                -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/documentation/undocumented_method_arguments.rb

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

data/lib/yard/lint/validators/documentation/undocumented_objects/config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedObjects
+          # Configuration for UndocumentedObjects validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :undocumented_objects
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning'
+            }.freeze
+            self.combines_with = ['Documentation/UndocumentedBooleanMethods'].freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_objects/messages_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedObjects
+          # Builds messages for undocumented objects offenses
+          class MessagesBuilder
+            class << self
+              # Build message for an undocumented object
+              # @param offense [Hash] offense data with :element key
+              # @return [String] formatted message
+              def call(offense)
+                "Documentation required for `#{offense[:element]}`"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_objects/parser.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedObjects
+          # Class used to extract details about undocumented objects from raw yard list output
+          # @example
+          #   /path/to/file.rb:3: UndocumentedClass
+          #   /path/to/file.rb:4: UndocumentedClass#method_one
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Regex used to parse yard list output format: file.rb:LINE: ObjectName
+            LINE_REGEX = /^(.+):(\d+): (.+)$/
+
+            # @param yard_list_output [String] raw yard list results string
+            # @return [Array<Hash>] Array with undocumented objects details
+            def call(yard_list_output)
+              yard_list_output
+                .split("\n")
+                .map(&:strip)
+                .reject(&:empty?)
+                .filter_map do |line|
+                  match = line.match(LINE_REGEX)
+                  next unless match
+
+                  {
+                    location: match[1],
+                    line: match[2].to_i,
+                    element: match[3]
+                  }
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_objects/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedObjects
+          # Result object for undocumented objects validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'UndocumentedObject'
+
+            # Build human-readable message for undocumented object offense
+            # @param offense [Hash] offense data
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_objects/validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedObjects
+          # Runs yard list to check for undocumented objects
+          class Validator < Base
+            # Query to find all objects without documentation
+            QUERY = "'docstring.blank?'"
+
+            private_constant :QUERY
+
+            private
+
+            # Runs yard list query 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 get the stats
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, escaped_file_names)
+              cmd = <<~CMD
+                yard list \
+                  #{shell_arguments} \
+                  --query #{QUERY} \
+                  -q \
+                  -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/documentation/undocumented_objects.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # UndocumentedObjects validator module
+        # This validator checks for missing documentation on objects
+        module UndocumentedObjects
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/semantic/abstract_methods/config.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Semantic
+        module AbstractMethods
+          # Configuration for AbstractMethods validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :abstract_methods
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning',
+              'AllowedImplementations' => [
+                'raise NotImplementedError',
+                'raise NotImplementedError, ".+"'
+              ]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/semantic/abstract_methods/messages_builder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Semantic validators - check code semantics and implementation correctness
+      module Semantic
+        module AbstractMethods
+          # Builds messages for abstract method offenses
+          class MessagesBuilder
+            class << self
+              # Build message for abstract method offense
+              # @param offense [Hash] offense data with :method_name key
+              # @return [String] formatted message
+              def call(offense)
+                "Abstract method `#{offense[:method_name]}` has implementation " \
+                  '(should only raise NotImplementedError or be empty)'
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/semantic/abstract_methods/parser.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Semantic
+        module AbstractMethods
+          # Parser for @abstract method validation results
+          class Parser < Parsers::Base
+            # @param yard_output [String] raw yard output with abstract method issues
+            # @return [Array<Hash>] array with abstract method violation details
+            def call(yard_output)
+              return [] if yard_output.nil? || yard_output.empty?
+
+              lines = yard_output.split("\n").reject(&:empty?)
+              results = []
+
+              lines.each_slice(2) do |location_line, status_line|
+                next unless location_line && status_line
+                next unless status_line == 'has_implementation'
+
+                # Parse location line: "file.rb:10: ClassName#method_name"
+                match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless match
+
+                file = match[1]
+                line = match[2].to_i
+                method_name = match[3]
+
+                results << {
+                  name: 'AbstractMethod',
+                  method_name: method_name,
+                  location: file,
+                  line: line
+                }
+              end
+
+              results
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/semantic/abstract_methods/result.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Semantic
+        module AbstractMethods
+          # Result object for abstract methods validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'method'
+            self.offense_name = 'AbstractMethodViolation'
+
+            # Build human-readable message for abstract method offense
+            # @param offense [Hash] offense data with :name key
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+
+            private
+
+            # Override to build offenses with dynamic names from parsed data
+            # @return [Array<Hash>] array of offense hashes
+            def build_offenses
+              @parsed_data.map do |offense_data|
+                {
+                  severity: configured_severity,
+                  type: self.class.offense_type,
+                  name: offense_data[:name] || self.class.offense_name,
+                  message: build_message(offense_data),
+                  location: offense_data[:location] || offense_data[:file],
+                  location_line: offense_data[:line] || offense_data[:location_line] || 0
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end