yard-lint 1.0.0 → 1.2.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/validator.rb

@@ -94,15 +94,13 @@ module Yard
 
             # @return [String] the enforced style ('type_after_name' (standard) or 'type_first')
             def enforced_style
-              config.validator_config('Tags/TagTypePosition', 'EnforcedStyle') || 'type_after_name'
+              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.validator_config(
-                'Tags/TagTypePosition', 'CheckedTags'
-              ) || %w[param option]
+              tags = config_or_default('CheckedTags')
               "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
             end
           end

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

@@ -4,8 +4,45 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # TagTypePosition validator module
-        # Detects type annotations in incorrect position (after param name instead of before)
+        # 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

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

@@ -4,8 +4,32 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # TypeSyntax validator module
-        # Validates YARD type syntax using YARD's TypesExplainer::Parser
+        # TypeSyntax validator
+        #
+        # Validates YARD type syntax using YARD's TypesExplainer::Parser. This
+        # validator ensures that type annotations can be properly parsed by YARD
+        # and follow YARD's type specification format. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Invalid type syntax that YARD cannot parse
+        #   # @param data [{String, Integer}] invalid hash syntax
+        #   # @return [String]] extra closing bracket
+        #   def process(data)
+        #   end
+        #
+        # @example Good - Valid parseable YARD type syntax
+        #   # @param data [Hash{String => Integer}] valid hash syntax
+        #   # @return [String] correct bracket usage
+        #   def process(data)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/TypeSyntax:
+        #       Enabled: false
+        #
         module TypeSyntax
         end
       end

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

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # DuplicatedParameterName validator module
+        # DuplicatedParameterName validator
+        #
+        # Detects duplicate `@param` tags for the same parameter name. If a parameter
+        # is documented multiple times, it's unclear which documentation is correct
+        # and can confuse both readers and YARD's parser. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Duplicate @param tags
+        #   # @param name [String] the name
+        #   # @param name [Symbol] oops, documented again
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Each parameter documented once
+        #   # @param name [String] the name
+        #   # @param age [Integer] the age
+        #   def process(name, age)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/DuplicatedParameterName:
+        #       Enabled: false
+        #
         module DuplicatedParameterName
         end
       end

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

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # InvalidDirectiveFormat validator module
+        # InvalidDirectiveFormat validator
+        #
+        # Detects malformed YARD directive syntax. Directives have specific format
+        # requirements (like `@!attribute [r] name` for read-only attributes), and
+        # this validator ensures those requirements are met. This validator is
+        # enabled by default.
+        #
+        # @example Bad - Malformed directive syntax
+        #   # @!attribute name missing brackets
+        #   # @!method [r] foo wrong format for method
+        #   class User
+        #   end
+        #
+        # @example Good - Correctly formatted directives
+        #   # @!attribute [r] name
+        #   # @!method foo(bar)
+        #   class User
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/InvalidDirectiveFormat:
+        #       Enabled: false
+        #
         module InvalidDirectiveFormat
         end
       end

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

@@ -5,7 +5,31 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # InvalidTagFormat validator module
+        # InvalidTagFormat validator
+        #
+        # Detects malformed YARD tag syntax. This validator checks that tags follow
+        # the correct format expected by YARD, such as proper spacing, brackets for
+        # types, and required components. This validator is enabled by default.
+        #
+        # @example Bad - Malformed tag syntax
+        #   # @param name[String] missing space before type
+        #   # @return [String the result missing closing bracket
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Correctly formatted tags
+        #   # @param name [String] the name
+        #   # @return [String] the result
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/InvalidTagFormat:
+        #       Enabled: false
+        #
         module InvalidTagFormat
         end
       end

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

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownDirective validator module
+        # UnknownDirective validator
+        #
+        # Detects usage of unrecognized YARD directives in documentation. Directives
+        # are special YARD commands (like `@!attribute`, `@!method`) that control
+        # documentation generation. This validator flags unknown directives that
+        # could indicate errors. This validator is enabled by default.
+        #
+        # @example Bad - Unknown or misspelled directive
+        #   # @!attribute [r] name
+        #   # @!method foo
+        #   class User
+        #   end
+        #
+        # @example Good - Standard YARD directives
+        #   # @!attribute [r] name
+        #   # @!method foo
+        #   class User
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownDirective:
+        #       Enabled: false
+        #
         module UnknownDirective
         end
       end

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

@@ -5,7 +5,29 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownParameterName validator module
+        # UnknownParameterName validator
+        #
+        # Detects `@param` tags that document parameters which don't exist in the
+        # method signature. This often occurs after refactoring when parameter names
+        # change but documentation isn't updated. This validator is enabled by default.
+        #
+        # @example Bad - @param documents non-existent parameter
+        #   # @param old_name [String] this parameter doesn't exist anymore
+        #   def process(new_name)
+        #   end
+        #
+        # @example Good - @param matches actual parameters
+        #   # @param new_name [String] the name to process
+        #   def process(new_name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownParameterName:
+        #       Enabled: false
+        #
         module UnknownParameterName
         end
       end

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

@@ -5,7 +5,32 @@ module Yard
     module Validators
       # Validators for checking YARD warnings
       module Warnings
-        # UnknownTag validator module
+        # UnknownTag validator
+        #
+        # Detects usage of unrecognized YARD tags in documentation. This validator
+        # checks against YARD's standard tag set and flags any tags that YARD
+        # doesn't recognize, which could indicate typos or unsupported tags.
+        # This validator is enabled by default.
+        #
+        # @example Bad - Misspelled or non-existent tags
+        #   # @param name [String] typo in param tag
+        #   # @returns [String] should be @return not @returns
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Standard YARD tags
+        #   # @param name [String] the name
+        #   # @return [String] the result
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/UnknownTag:
+        #       Enabled: false
+        #
         module UnknownTag
         end
       end

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.0.0'
+    VERSION = '1.2.0'
   end
 end

data/lib/yard/lint.rb

@@ -19,10 +19,20 @@ module Yard
       # @param config_file [String, nil] path to config file
       #   (auto-loads .yard-lint.yml if not specified)
       # @param progress [Boolean] show progress indicator (default: true for TTY)
+      # @param diff [Hash, nil] diff mode options
+      #   - :mode [Symbol] one of :ref, :staged, :changed
+      #   - :base_ref [String, nil] base ref for :ref mode (auto-detects main/master if nil)
       # @return [Yard::Lint::Result] result object with offenses
-      def run(path:, config: nil, config_file: nil, progress: nil)
+      def run(path:, config: nil, config_file: nil, progress: nil, diff: nil)
         config ||= load_config(config_file)
-        files = expand_path(path, config)
+
+        # Determine files to lint based on diff mode or normal path expansion
+        files = if diff
+                  get_diff_files(diff, path, config)
+                else
+                  expand_path(path, config)
+                end
+
         runner = Runner.new(files, config)
 
         # Enable progress by default if output is a TTY
@@ -45,6 +55,32 @@ module Yard
         end
       end
 
+      # Get files from git diff based on diff mode
+      # @param diff [Hash] diff mode options
+      # @param path [String, Array<String>] path or array of paths to filter within
+      # @param config [Yard::Lint::Config] configuration object
+      # @return [Array<String>] array of absolute file paths
+      def get_diff_files(diff, path, config)
+        # Get changed files from git based on mode
+        git_files = case diff[:mode]
+                    when :ref
+                      Git.changed_files(diff[:base_ref], path)
+                    when :staged
+                      Git.staged_files(path)
+                    when :changed
+                      Git.uncommitted_files(path)
+                    else
+                      raise ArgumentError, "Unknown diff mode: #{diff[:mode]}"
+                    end
+
+        # Apply exclusion patterns
+        git_files.reject do |file|
+          config.exclude.any? do |pattern|
+            File.fnmatch(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+        end
+      end
+
       # Expand path/glob patterns into an array of files
       # @param path [String, Array<String>] path or array of paths
       # @param config [Yard::Lint::Config] configuration object

data/lib/yard-lint.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+# Load IRB notifier shim before YARD to avoid IRB dependency in Ruby 3.5+
+# This must be loaded before any YARD code is required
+require_relative 'yard/lint/ext/irb_notifier_shim'
+
 require 'zeitwerk'
 
 # Setup Zeitwerk loader for gem
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.ignore(__FILE__)
+loader.ignore("#{__dir__}/yard/lint/ext")
 loader.setup
 
 # Manually load the main module since it contains class-level methods

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -60,9 +60,12 @@ files:
 - lib/yard/lint.rb
 - lib/yard/lint/command_cache.rb
 - lib/yard/lint/config.rb
+- lib/yard/lint/config_generator.rb
 - lib/yard/lint/config_loader.rb
 - lib/yard/lint/errors.rb
+- lib/yard/lint/ext/irb_notifier_shim.rb
 - lib/yard/lint/formatters/progress.rb
+- lib/yard/lint/git.rb
 - lib/yard/lint/parsers/base.rb
 - lib/yard/lint/parsers/one_line_base.rb
 - lib/yard/lint/parsers/two_line_base.rb
@@ -70,8 +73,15 @@ files:
 - lib/yard/lint/results/aggregate.rb
 - lib/yard/lint/results/base.rb
 - lib/yard/lint/runner.rb
+- lib/yard/lint/stats_calculator.rb
 - lib/yard/lint/validators/base.rb
 - lib/yard/lint/validators/config.rb
+- lib/yard/lint/validators/documentation/markdown_syntax.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/config.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/messages_builder.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/parser.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/result.rb
+- lib/yard/lint/validators/documentation/markdown_syntax/validator.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/config.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/parser.rb
@@ -89,6 +99,11 @@ files:
 - lib/yard/lint/validators/documentation/undocumented_objects/parser.rb
 - lib/yard/lint/validators/documentation/undocumented_objects/result.rb
 - lib/yard/lint/validators/documentation/undocumented_objects/validator.rb
+- lib/yard/lint/validators/documentation/undocumented_options.rb
+- lib/yard/lint/validators/documentation/undocumented_options/config.rb
+- lib/yard/lint/validators/documentation/undocumented_options/parser.rb
+- lib/yard/lint/validators/documentation/undocumented_options/result.rb
+- lib/yard/lint/validators/documentation/undocumented_options/validator.rb
 - lib/yard/lint/validators/semantic/abstract_methods.rb
 - lib/yard/lint/validators/semantic/abstract_methods/config.rb
 - lib/yard/lint/validators/semantic/abstract_methods/messages_builder.rb
@@ -107,6 +122,12 @@ files:
 - lib/yard/lint/validators/tags/collection_type/parser.rb
 - lib/yard/lint/validators/tags/collection_type/result.rb
 - lib/yard/lint/validators/tags/collection_type/validator.rb
+- lib/yard/lint/validators/tags/example_syntax.rb
+- lib/yard/lint/validators/tags/example_syntax/config.rb
+- lib/yard/lint/validators/tags/example_syntax/messages_builder.rb
+- lib/yard/lint/validators/tags/example_syntax/parser.rb
+- lib/yard/lint/validators/tags/example_syntax/result.rb
+- lib/yard/lint/validators/tags/example_syntax/validator.rb
 - lib/yard/lint/validators/tags/invalid_types.rb
 - lib/yard/lint/validators/tags/invalid_types/config.rb
 - lib/yard/lint/validators/tags/invalid_types/messages_builder.rb
@@ -131,6 +152,12 @@ files:
 - lib/yard/lint/validators/tags/order/parser.rb
 - lib/yard/lint/validators/tags/order/result.rb
 - lib/yard/lint/validators/tags/order/validator.rb
+- lib/yard/lint/validators/tags/redundant_param_description.rb
+- lib/yard/lint/validators/tags/redundant_param_description/config.rb
+- lib/yard/lint/validators/tags/redundant_param_description/messages_builder.rb
+- lib/yard/lint/validators/tags/redundant_param_description/parser.rb
+- lib/yard/lint/validators/tags/redundant_param_description/result.rb
+- lib/yard/lint/validators/tags/redundant_param_description/validator.rb
 - lib/yard/lint/validators/tags/tag_type_position.rb
 - lib/yard/lint/validators/tags/tag_type_position/config.rb
 - lib/yard/lint/validators/tags/tag_type_position/messages_builder.rb