yard-lint 0.2.1 → 1.1.0

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Tags validators - validate YARD tag quality and consistency
+      module Tags
+        # RedundantParamDescription validator
+        #
+        # Detects parameter descriptions that add no meaningful information beyond
+        # what's already obvious from the parameter name and type. This validator
+        # helps maintain high-quality documentation by flagging descriptions that
+        # should either be expanded with meaningful details or removed entirely.
+        #
+        # ## Why This Matters
+        #
+        # Documentation is most valuable when AI assistants and human developers
+        # can trust it. Redundant descriptions like `@param user [User] The user`
+        # create noise without adding value, training both humans and AI to ignore
+        # parameter documentation. Better to have no description (letting the type
+        # speak for itself) than a redundant one.
+        #
+        # @example Redundant - Article + param name (will be flagged)
+        #   # @param appointment [Appointment] The appointment
+        #   # @param user [User] the user
+        #   def process(appointment, user)
+        #   end
+        #
+        # @example Redundant - Possessive form (will be flagged)
+        #   # @param appointment [Appointment] The event's appointment
+        #   def schedule(appointment)
+        #   end
+        #
+        # @example Redundant - Type restatement (will be flagged)
+        #   # @param user [User] User object
+        #   # @param value [Integer] Integer value
+        #   def update(user, value)
+        #   end
+        #
+        # @example Redundant - Parameter to verb pattern (will be flagged)
+        #   # @param payments [Array] Payments to count
+        #   # @param user [User] User to notify
+        #   def process(payments, user)
+        #   end
+        #
+        # @example Redundant - ID pattern (will be flagged)
+        #   # @param treatment_id [String] ID of the treatment
+        #   # @param uuid [String] Unique identifier for the list
+        #   def find(treatment_id, uuid)
+        #   end
+        #
+        # @example Redundant - Directional date (will be flagged)
+        #   # @param from [Date] from this date
+        #   # @param till [Date] till this date
+        #   def filter(from, till)
+        #   end
+        #
+        # @example Redundant - Type + generic term (will be flagged)
+        #   # @param payment [Payment] Payment object
+        #   # @param data [Hash] Hash data
+        #   def process(payment, data)
+        #   end
+        #
+        # @example Good - No description (type is self-explanatory)
+        #   # @param appointment [Appointment]
+        #   # @param user [User]
+        #   def process(appointment, user)
+        #   end
+        #
+        # @example Good - Long, meaningful descriptions with context
+        #   # @param date [Date, nil] the date that can describe the event starting information or nil if event did not yet start
+        #   # @param user [User] the user who initiated the request and will receive notifications
+        #   # @param data [Hash] configuration options for the API endpoint including timeout and retry settings
+        #   def configure(date, user, data)
+        #   end
+        #
+        # @example Good - Short but adds value beyond param name
+        #   # @param count [Integer] maximum number of retries before giving up
+        #   # @param timeout [Integer] seconds to wait before timing out the connection
+        #   # @param enabled [Boolean] whether the feature is enabled for this account
+        #   def setup(count, timeout, enabled)
+        #   end
+        #
+        # @example Good - Starts similar but continues with valuable info
+        #   # @param user [User] the current user, or guest if not authenticated
+        #   # @param data [Hash] the request payload containing user preferences
+        #   # @param id [String] unique identifier used for tracking across systems
+        #   def track(user, data, id)
+        #   end
+        #
+        # ## Configuration
+        #
+        # The validator is highly configurable to match your project's needs:
+        #
+        #     Tags/RedundantParamDescription:
+        #       Description: 'Detects meaningless parameter descriptions.'
+        #       Enabled: true
+        #       Severity: convention
+        #       CheckedTags:
+        #         - param
+        #         - option
+        #       # Articles that trigger the article_param pattern
+        #       Articles:
+        #         - The
+        #         - the
+        #         - A
+        #         - a
+        #         - An
+        #         - an
+        #       # Maximum word count for redundant descriptions (longer descriptions are never flagged)
+        #       MaxRedundantWords: 6
+        #       # Generic terms that trigger the type_generic pattern
+        #       GenericTerms:
+        #         - object
+        #         - instance
+        #         - value
+        #         - data
+        #         - item
+        #         - element
+        #       # Pattern toggles (enable/disable specific detection patterns)
+        #       EnabledPatterns:
+        #         ArticleParam: true        # "The user", "the appointment"
+        #         PossessiveParam: true     # "The event's appointment"
+        #         TypeRestatement: true     # "User object", "Appointment"
+        #         ParamToVerb: true         # "Payments to count"
+        #         IdPattern: true           # "ID of the treatment" for *_id params
+        #         DirectionalDate: true     # "from this date" for from/to/till
+        #         TypeGeneric: true         # "Payment object", "Hash data"
+        #
+        # ## Pattern Types
+        #
+        # The validator detects 7 different redundancy patterns:
+        #
+        # 1. **ArticleParam**: `"The user"`, `"the appointment"` - Article + parameter name
+        # 2. **PossessiveParam**: `"The event's appointment"` - Possessive form + parameter name
+        # 3. **TypeRestatement**: `"User object"`, `"Appointment"` - Just repeats the type
+        # 4. **ParamToVerb**: `"Payments to count"` - Parameter name + "to" + verb
+        # 5. **IdPattern**: `"ID of the treatment"` - For `_id` or `_uuid` suffixed parameters
+        # 6. **DirectionalDate**: `"from this date"` - For `from`, `to`, `till` parameters
+        # 7. **TypeGeneric**: `"Payment object"` - Type + generic term like "object", "instance"
+        #
+        # You can disable individual patterns while keeping others enabled.
+        #
+        # ## False Positive Prevention
+        #
+        # The validator uses multiple strategies to prevent false positives:
+        #
+        # 1. **Word count threshold**: Descriptions longer than `MaxRedundantWords` (default: 6)
+        #    are never flagged, even if they start with a redundant pattern
+        # 2. **EXACT pattern matching**: Only flags complete matches, not partial/prefix matches
+        # 3. **Configurable patterns**: Disable patterns that don't work for your codebase
+        #
+        # This means `"the date that can describe the event starting information"` (9 words)
+        # will never be flagged, even though it starts with "the date".
+        #
+        # ## Disabling
+        #
+        # To disable this validator:
+        #
+        #     Tags/RedundantParamDescription:
+        #       Enabled: false
+        #
+        module RedundantParamDescription
+        end
+      end
+    end
+  end
+end

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,111 @@
+# 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_or_default('EnforcedStyle')
+            end
+
+            # Array of tag names to check, formatted for YARD query
+            # @return [String] Ruby array literal string
+            def checked_tags_array
+              tags = config_or_default('CheckedTags')
+              "[#{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,51 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # TagTypePosition validator
+        #
+        # Ensures consistent type annotation positioning in YARD documentation tags.
+        # By default, it enforces YARD standard style where the type appears after
+        # the parameter name (`@param name [Type]`), but you can configure it to
+        # enforce `type_first` style if your team prefers that convention.
+        # This validator is enabled by default.
+        #
+        # @example Good - Type after parameter name (YARD standard)
+        #   # @param name [String] the user's name
+        #   # @param age [Integer] the user's age
+        #   # @param options [Hash{Symbol => Object}] configuration options
+        #   def create_user(name, age, options = {})
+        #   end
+        #
+        # @example Bad - Type before parameter name (when using default style)
+        #   # @param [String] name the user's name
+        #   # @param [Integer] age the user's age
+        #   def create_user(name, age)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To use type_first style instead:
+        #
+        #     Tags/TagTypePosition:
+        #       EnforcedStyle: type_first
+        #
+        # @example Good - When EnforcedStyle is type_first
+        #   # @param [String] name the user's name
+        #   # @param [Integer] age the user's age
+        #   def create_user(name, age)
+        #   end
+        #
+        # To disable this validator:
+        #
+        #     Tags/TagTypePosition:
+        #       Enabled: false
+        #
+        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