yard-lint 0.2.0 → 1.0.0

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Validates that @param/@option tags only appear on methods
+          class Validator < Base
+            private
+
+            # Runs YARD query to find @param/@option tags on non-methods
+            # @param dir [String] directory where YARD database is stored
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
+            # @return [Hash] shell command execution results
+            def yard_cmd(dir, file_list_path)
+              # Write query to a temporary file to avoid shell escaping issues
+              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{query} "
+
+              Tempfile.create(['yard_query', '.sh']) do |f|
+                f.write("#!/bin/bash\n")
+                f.write(cmd)
+                f.write("--private --protected #{shell_arguments} -b #{Shellwords.escape(dir)}\n")
+                f.flush
+                f.chmod(0o755)
+
+                shell("bash #{Shellwords.escape(f.path)}")
+              end
+            end
+
+            # YARD query that finds method-only tags on non-method objects
+            # Format output as two lines per violation:
+            #   Line 1: file.rb:LINE: ClassName
+            #   Line 2: object_type|tag_name
+            # @return [String] YARD query string
+            def query
+              <<~QUERY.strip
+                '
+                object_type = object.type.to_s
+
+                if #{invalid_object_types_array}.include?(object_type)
+                  docstring.tags.each do |tag|
+                    if #{checked_tags_array}.include?(tag.tag_name)
+                      puts object.file + ":" + object.line.to_s + ": " + object.title
+                      puts object_type + "|" + tag.tag_name
+                      break
+                    end
+                  end
+                end
+
+                false
+                '
+              QUERY
+            end
+
+            # Array of tag names to check, formatted for YARD query
+            # @return [String] Ruby array literal string
+            def checked_tags_array
+              "[#{checked_tags.map { |t| "\"#{t}\"" }.join(',')}]"
+            end
+
+            # Array of invalid object types, formatted for YARD query
+            # @return [String] Ruby array literal string
+            def invalid_object_types_array
+              "[#{invalid_object_types.map { |t| "\"#{t}\"" }.join(',')}]"
+            end
+
+            # @return [Array<String>] tags that should only appear on methods
+            def checked_tags
+              config.validator_config('Tags/MeaninglessTag', 'CheckedTags') || %w[param option]
+            end
+
+            # @return [Array<String>] object types that shouldn't have method-only tags
+            def invalid_object_types
+              config.validator_config('Tags/MeaninglessTag', 'InvalidObjectTypes') || %w[
+                class module constant
+              ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # MeaninglessTag validator module
+        # Detects @param and @option tags on classes, modules, or constants
+        # (these tags only make sense on methods)
+        module MeaninglessTag
+        end
+      end
+    end
+  end
+end

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

@@ -11,15 +11,14 @@ module Yard
 
             # 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
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard list \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
                 --private \
                 --protected \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
               cmd = cmd.gsub('yard list', "yard list --query #{query}")

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

@@ -12,16 +12,15 @@ module Yard
 
             # 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
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard list \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
                 --private \
                 --protected \
                 --query #{query} \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
 
               result = shell(cmd)

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagTypePosition
+          # Configuration for TagTypePosition validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :tag_type_position
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'convention',
+              'CheckedTags' => %w[param option],
+              'EnforcedStyle' => 'type_after_name' # 'type_after_name' (standard) or 'type_first'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagTypePosition
+          # Builds human-readable messages for TagTypePosition violations
+          class MessagesBuilder
+            class << self
+              # Formats a violation message
+              # @param offense [Hash] the offense details
+              # @return [String] formatted message
+              def call(offense)
+                tag_name = offense[:tag_name]
+                param_name = offense[:param_name]
+                type_info = offense[:type_info]
+                detected_style = offense[:detected_style]
+
+                if detected_style == 'type_after_name'
+                  # Enforcing type_first, but found type_after_name
+                  "Type should appear before parameter name in @#{tag_name} tag. " \
+                    "Use '@#{tag_name} [#{type_info}] #{param_name}' instead of " \
+                    "'@#{tag_name} #{param_name} [#{type_info}]'."
+                else
+                  # Enforcing type_after_name, but found type_first
+                  "Type should appear after parameter name in @#{tag_name} tag. " \
+                    "Use '@#{tag_name} #{param_name} [#{type_info}]' instead of " \
+                    "'@#{tag_name} [#{type_info}] #{param_name}'."
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagTypePosition
+          # Parses YARD output for TagTypePosition violations
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses YARD query output into structured violation data
+            # @param yard_output [String] raw output from YARD query
+            # @param _kwargs [Hash] additional keyword arguments (unused)
+            # @return [Array<Hash>] array of violation hashes
+            def call(yard_output, **_kwargs)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+              violations = []
+
+              lines.each_slice(2) do |location_line, details_line|
+                next unless location_line && details_line
+
+                # Parse location: "file.rb:10: ClassName#method_name"
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # Parse details: "tag_name|param_name|type_info|detected_style"
+                details = details_line.split('|', 4)
+                next unless details.size >= 3
+
+                tag_name, param_name, type_info, detected_style = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  tag_name: tag_name,
+                  param_name: param_name,
+                  type_info: type_info,
+                  detected_style: detected_style
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagTypePosition
+          # Result wrapper for TagTypePosition violations
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'style'
+            self.offense_name = 'TagTypePosition'
+
+            # Builds a human-readable message for a violation
+            # @param offense [Hash] the offense details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagTypePosition
+          # Validates type annotation position in @param and @option tags
+          # YARD standard (type_after_name): @param name [String] description
+          # Alternative (type_first): @param name [String] description
+          #
+          # Note: @return tags are not checked as they don't have parameter names
+          class Validator < Base
+            private
+
+            # Runs YARD query to check type position in tags
+            # @param dir [String] directory where YARD database is stored
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
+            # @return [Hash] shell command execution results
+            def yard_cmd(dir, file_list_path)
+              # Write query to a temporary file to avoid shell escaping issues
+              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{query} "
+
+              Tempfile.create(['yard_query', '.sh']) do |f|
+                f.write("#!/bin/bash\n")
+                f.write(cmd)
+                f.write("#{shell_arguments} -b #{Shellwords.escape(dir)}\n")
+                f.flush
+                f.chmod(0o755)
+
+                shell("bash #{Shellwords.escape(f.path)}")
+              end
+            end
+
+            # YARD query that checks source code directly instead of docstring.all
+            # Detects patterns based on configured style
+            # @return [String] YARD query string
+            def query
+              <<~QUERY.strip
+                '
+                require "ripper"
+
+                checked_tags = #{checked_tags_array}
+                enforced_style = "#{enforced_style}"
+
+                # Read the source file and find comment lines for this object
+                return false unless object.file && File.exist?(object.file)
+
+                source_lines = File.readlines(object.file)
+                start_line = [object.line - 50, 0].max
+                end_line = [object.line, source_lines.length - 1].min
+
+                # Look for comments before the object definition
+                # Start just before the object line and scan backward
+                (start_line...(end_line - 1)).reverse_each do |line_num|
+                  line = source_lines[line_num].to_s.strip
+
+                  # Skip empty lines
+                  next if line.empty?
+
+                  # Stop if we hit code (non-comment line)
+                  break unless line.start_with?("#")
+
+                  # Skip comment-only lines without tags
+                  next unless line.include?("@")
+
+                  checked_tags.each do |tag_name|
+                    if enforced_style == "type_first"
+                      # Detect: @tag_name word [Type] (violation when type_first is enforced)
+                      pattern = /@\#{tag_name}\\s+(\\w+)\\s+\\[([^\\]]+)\\]/
+                      if line =~ pattern
+                        param_name = $1
+                        type_info = $2
+                        puts object.file + ":" + (line_num + 1).to_s + ": " + object.title
+                        puts tag_name + "|" + param_name + "|" + type_info + "|type_after_name"
+                      end
+                    else
+                      # Detect: @tag_name [Type] word (violation when type_after_name is enforced)
+                      pattern = /@\#{tag_name}\\s+\\[([^\\]]+)\\]\\s+(\\w+)/
+                      if line =~ pattern
+                        type_info = $1
+                        param_name = $2
+                        puts object.file + ":" + (line_num + 1).to_s + ": " + object.title
+                        puts tag_name + "|" + param_name + "|" + type_info + "|type_first"
+                      end
+                    end
+                  end
+                end
+
+                false
+                '
+              QUERY
+            end
+
+            # @return [String] the enforced style ('type_after_name' (standard) or 'type_first')
+            def enforced_style
+              config.validator_config('Tags/TagTypePosition', 'EnforcedStyle') || 'type_after_name'
+            end
+
+            # Array of tag names to check, formatted for YARD query
+            # @return [String] Ruby array literal string
+            def checked_tags_array
+              tags = config.validator_config(
+                'Tags/TagTypePosition', 'CheckedTags'
+              ) || %w[param option]
+              "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # TagTypePosition validator module
+        # Detects type annotations in incorrect position (after param name instead of before)
+        module TagTypePosition
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TypeSyntax
+          # Builds human-readable messages for type syntax violations
+          class MessagesBuilder
+            class << self
+              # Formats a type syntax violation message
+              # @param offense [Hash] offense details with tag_name, type_string, error_message
+              # @return [String] formatted message
+              def call(offense)
+                tag = offense[:tag_name]
+                type = offense[:type_string]
+                error = offense[:error_message]
+
+                "Invalid type syntax in @#{tag} tag: '#{type}' (#{error})"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TypeSyntax
+          # Parser for TypeSyntax validator output
+          # Parses YARD query output that reports type syntax errors
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses YARD output and extracts type syntax violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ClassName#method_name
+            #   tag_name|type_string|error_message
+            # @param yard_output [String] raw YARD query results
+            # @param _kwargs [Hash] unused keyword arguments (for compatibility)
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **_kwargs)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+              violations = []
+
+              lines.each_slice(2) do |location_line, details_line|
+                next unless location_line && details_line
+
+                # Parse location: "file.rb:10: ClassName#method_name"
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # Parse details: "tag_name|type_string|error_message"
+                details = details_line.split('|', 3)
+                next unless details.size == 3
+
+                tag_name, type_string, error_message = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  method_name: location_match[3],
+                  tag_name: tag_name,
+                  type_string: type_string,
+                  error_message: error_message
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TypeSyntax
+          # Result wrapper for TypeSyntax validator
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'method'
+            self.offense_name = 'InvalidTypeSyntax'
+
+            # Builds a human-readable message for the offense
+            # @param offense [Hash] offense details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TypeSyntax
+          # Runs YARD to validate type syntax using TypesExplainer::Parser
+          class Validator < Base
+            private
+
+            # Runs YARD query to validate type syntax on given files
+            # @param dir [String] directory where YARD database is stored
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
+            # @return [Hash] shell command execution results
+            def yard_cmd(dir, file_list_path)
+              # Write query to a temporary file to avoid shell escaping issues
+              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{query} "
+
+              Tempfile.create(['yard_query', '.sh']) do |f|
+                f.write("#!/bin/bash\n")
+                f.write(cmd)
+                f.write("#{shell_arguments} -b #{Shellwords.escape(dir)}\n")
+                f.flush
+                f.chmod(0o755)
+
+                shell("bash #{Shellwords.escape(f.path)}")
+              end
+            end
+
+            # YARD query that validates type syntax for each tag
+            # Format output as two lines per violation:
+            #   Line 1: file.rb:LINE: ClassName#method_name
+            #   Line 2: tag_name|type_string|error_message
+            # @return [String] YARD query string
+            def query
+              <<~QUERY.strip
+                '
+                require "yard"
+
+                docstring
+                  .tags
+                  .select { |tag| #{validated_tags_array}.include?(tag.tag_name) }
+                  .each do |tag|
+                    next unless tag.types
+
+                    tag.types.each do |type_str|
+                      begin
+                        YARD::Tags::TypesExplainer::Parser.parse(type_str)
+                      rescue SyntaxError => e
+                        puts object.file + ":" + object.line.to_s + ": " + object.title
+                        puts tag.tag_name + "|" + type_str + "|" + e.message
+                        break
+                      end
+                    end
+                  end
+
+                false
+                '
+              QUERY
+            end
+
+            # Array of tag names to validate, formatted for YARD query
+            # @return [String] Ruby array literal string
+            def validated_tags_array
+              tags = config.validator_config('Tags/TypeSyntax', 'ValidatedTags') || %w[
+                param option return yieldreturn
+              ]
+              "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # TypeSyntax validator module
+        # Validates YARD type syntax using YARD's TypesExplainer::Parser
+        module TypeSyntax
+        end
+      end
+    end
+  end
+end

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

@@ -11,15 +11,14 @@ module Yard
 
             # 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
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard stats \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
                   #{shell_arguments} \
                 --compact \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')