yard-lint 0.2.0

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Semantic
+        module AbstractMethods
+          # Validator to check @abstract methods have proper implementation
+          class Validator < Base
+            private
+
+            # Runs YARD list query to find abstract methods with implementation
+            # @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 run YARD
+            # @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 abstract methods with implementation
+            def query
+              <<~QUERY
+                '
+                  if object.has_tag?(:abstract) && object.is_a?(YARD::CodeObjects::MethodObject)
+                      # Check if method has actual implementation (not just NotImplementedError)
+                    source = object.source rescue nil
+                    if source && !source.empty?
+                        # Simple heuristic: abstract methods should be empty or raise NotImplementedError
+                      lines = source.split("\\n").map(&:strip).reject(&:empty?)
+                        # Skip def line and end
+                      body_lines = lines[1...-1] || []
+
+                      has_real_implementation = body_lines.any? do |line|
+                        !line.start_with?('#') &&
+                        !line.include?('NotImplementedError') &&
+                        !line.include?('raise') &&
+                        line != 'end'
+                        end
+
+                      if has_real_implementation
+                        puts object.file + ':' + object.line.to_s + ': ' + object.title
+                        puts 'has_implementation'
+                        end
+                      end
+                    end
+                  false
+                '
+              QUERY
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ApiTags
+          # Configuration for ApiTags validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :api_tags
+            self.defaults = {
+              'Enabled' => false,
+              'Severity' => 'warning',
+              'AllowedApis' => %w[public private internal]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Tags validators - validate YARD tag quality and consistency
+      module Tags
+        module ApiTags
+          # Builds messages for API tag offenses
+          class MessagesBuilder
+            class << self
+              # Build message for API tag offense
+              # @param offense [Hash] offense data with :status and :object_name keys
+              # @return [String] formatted message
+              def call(offense)
+                if offense[:status] == 'missing'
+                  "Public object `#{offense[:object_name]}` is missing @api tag"
+                else
+                  api_value = offense[:api_value] || offense[:status]&.sub('invalid:', '')
+                  "Object `#{offense[:object_name]}` has invalid @api tag value: '#{api_value}'"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ApiTags
+          # Parser for @api tag validation results
+          class Parser < Parsers::Base
+            # @param yard_output [String] raw yard output with API tag issues
+            # @return [Array<Hash>] array with API tag 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
+
+                # 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
+                object_name = match[3]
+
+                api_value = if status_line.start_with?('invalid:')
+                              status_line.sub('invalid:', '')
+                            end
+
+                results << {
+                  name: 'ApiTag',
+                  object_name: object_name,
+                  status: status_line,
+                  api_value: api_value,
+                  location: file,
+                  line: line
+                }
+              end
+
+              results
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ApiTags
+          # Result object for API tag validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'ApiTagViolation'
+
+            # Build human-readable message for API tag 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

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ApiTags
+          # Validator to check for @api tag presence and validity
+          class Validator < Base
+            private
+
+            # Runs yard list query to find objects missing or with invalid @api 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 objects with missing or invalid @api tags
+            def query
+              allowed_list = allowed_apis.map { |api| "'#{api}'" }.join(', ')
+
+              <<~QUERY
+                '
+                  if object.has_tag?(:api)
+                    api_value = object.tag(:api).text
+                    unless [#{allowed_list}].include?(api_value)
+                      puts object.file + ':' + object.line.to_s + ': ' + object.title
+                      puts 'invalid:' + api_value
+                      end
+                  elsif #{require_api_tags?}
+                      # Only check public methods/classes if require_api_tags is enabled
+                    visibility = object.visibility.to_s
+                    if visibility == 'public' && !object.root?
+                      puts object.file + ':' + object.line.to_s + ': ' + object.title
+                      puts 'missing'
+                      end
+                    end
+                  false
+                '
+              QUERY
+            end
+
+            # @return [Array<String>] list of allowed API values
+            def allowed_apis
+              config.validator_config('Tags/ApiTags', 'AllowedApis') || %w[public private internal]
+            end
+
+            # @return [Boolean] whether @api tags are required on public objects
+            def require_api_tags?
+              config.validator_enabled?('Tags/ApiTags')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InvalidTypes
+          # Configuration for InvalidTypes validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :invalid_types
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning',
+              'ValidatedTags' => %w[param option return yieldreturn],
+              'ExtraTypes' => []
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InvalidTypes
+          # Builds messages for invalid tag types offenses
+          class MessagesBuilder
+            class << self
+              # Build message for invalid tag types
+              # @param offense [Hash] offense data with :method_name key
+              # @return [String] formatted message
+              def call(offense)
+                "The `#{offense[:method_name]}` has at least one tag " \
+                  'with an invalid type definition.'
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InvalidTypes
+          # Parser for invalid tags types output
+          # Reuses location parsing logic from undocumented method arguments
+          class Parser < Validators::Documentation::UndocumentedMethodArguments::Parser
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InvalidTypes
+          # Result object for invalid tag types validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'method'
+            self.offense_name = 'InvalidTagType'
+
+            # Build human-readable message for invalid tag type 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/tags/invalid_types/validator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InvalidTypes
+          # Runs a query that will pick all the objects that have invalid type definitions
+          # By invalid we mean, that they are not classes nor any of the allowed defaults or
+          # exclusions.
+          class Validator < Base
+            # All non-class yard types that are considered valid
+            ALLOWED_DEFAULTS = %w[
+              false
+              true
+              nil
+              self
+              vold
+            ].freeze
+
+            private_constant :ALLOWED_DEFAULTS
+
+            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)
+              # Write query to a temporary file to avoid shell escaping issues
+              require 'tempfile'
+
+              Tempfile.create(['yard_query', '.sh']) do |f|
+                f.write("#!/bin/bash\n")
+                f.write("yard list --query #{Shellwords.escape(query)} ")
+                f.write("--private --protected -b #{Shellwords.escape(dir)} ")
+                f.write("#{escaped_file_names}\n")
+                f.flush
+                f.chmod(0o755)
+
+                shell("bash #{Shellwords.escape(f.path)}")
+              end
+            end
+
+            # @return [String] multiline yard query that we use to find methods with
+            #   tags with invalid types definitions
+            def query
+              <<-QUERY
+                '
+                  sanitize = ->(type) do
+                    type
+                      .tr('=>', '')
+                      .tr('<', '')
+                      .tr('>', '')
+                      .tr(' ', '')
+                      .tr(',', '')
+                      .tr('{', '')
+                      .tr('}', '')
+                  end
+
+                  docstring
+                    .tags
+                    .select { |tag| #{checked_tags_names}.include?(tag.tag_name) }
+                    .map(&:types)
+                    .flatten
+                    .uniq
+                    .compact
+                    .map(&sanitize)
+                    .reject { |type| #{allowed_types_code}.include?(type) }
+                    .reject { |type| !(Kernel.const_defined?(type) rescue nil).nil? }
+                    .reject { |type| type.include?('#') }
+                    .then { |types| !types.empty? }
+                '
+              QUERY
+            end
+
+            # @return [String] tags names for which we want to check the invalid tags
+            #   types definitions
+            def checked_tags_names
+              validated_tags = config.validator_config('Tags/InvalidTypes', 'ValidatedTags')
+              query_array(validated_tags)
+            end
+
+            # @return [String] extra names that we allow for types definitions in a yard
+            #   query acceptable form
+            def allowed_types_code
+              extra_types = config.validator_config('Tags/InvalidTypes', 'ExtraTypes') || []
+              query_array(ALLOWED_DEFAULTS + extra_types)
+            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/invalid_types.rb

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OptionTags
+          # Configuration for OptionTags validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :option_tags
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning',
+              'ParameterNames' => %w[options opts kwargs]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OptionTags
+          # Builds messages for option tag offenses
+          class MessagesBuilder
+            class << self
+              # Build message for option tag offense
+              # @param offense [Hash] offense data with :method_name key
+              # @return [String] formatted message
+              def call(offense)
+                "Method `#{offense[:method_name]}` has options parameter but no @option tags " \
+                  'documenting the available options'
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OptionTags
+          # Parser for @option tag validation results
+          class Parser < Parsers::Base
+            # @param yard_output [String] raw yard output with option tag issues
+            # @return [Array<Hash>] array with option tag 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 == 'missing_option_tags'
+
+                # 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: 'MissingOptionTags',
+                  method_name: method_name,
+                  location: file,
+                  line: line
+                }
+              end
+
+              results
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OptionTags
+          # Result object for option tag validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'method'
+            self.offense_name = 'OptionTagViolation'
+
+            # Build human-readable message for option tag 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