yard-lint 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 670e09e8becdbcef0090965d61aeb47e488601119775ed33b5b6a99d50e04145
-  data.tar.gz: 0c1b99fa7aa6357948895c7e120adae3a59f3a0f0bc6da6fc48c5191a62d78f3
+  metadata.gz: 7e34cf3a1c023498c1fe762550cde88ce865a5bac461b2a8d40540ce883f39bc
+  data.tar.gz: 60a3553d7e7728c74eab25b31886c8a5acb5018a1abd933d82ab0df3e00737c8
 SHA512:
-  metadata.gz: 164679ca8bdee70f43561bfeecaa3bee67705c046f77466833469920142733f1311cf19ac5d5856db08f6372200760eb8bb6fbc29170c84b2f48722fc803bbff
-  data.tar.gz: b87edd3236cb9aed11e4e61764507678c77fd3a3a1eb887874ac59e9cd255e7e78cc19152a56d8c471762028054268b3d593727ec2f8c7b781ca3060eec9be88
+  metadata.gz: ccf09341a5bae5a35815fada582e1eaa3856e2997638f7c61a5b8e80ebdfac49c0c8e263ec469694da719501aa2ef23d4aa81750da1b7e101d614a652a14e7a3
+  data.tar.gz: b3b0b92de7f0a63506abf5e90e4baef22479098c694e0c7a7fcde5a7f9f4939ad0f7630c7f068ac9ec6c3fa43176df10c22904dc86b0954a6c1dafa452d98577

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.12.0 (2026-09-23)
+- **[Feature]** Added `--explain VALIDATOR` - prints a validator's description, default severity, configuration options, and Bad/Good examples directly in the terminal, so you no longer need the wiki to understand or tune a rule. The explanation is extracted from the validator's own YARD documentation block (e.g. `lib/yard/lint/validators/tags/type_syntax.rb`), parsed with YARD - the linter reads its own YARD docs to explain itself, which keeps those doc blocks accurate. Unknown names get "did you mean" suggestions and the full validator list, mirroring `--only`.
+- **[Bugfix]** `Tags/TagSeparator` and `Tags/TagGroupSeparator` no longer report false positives caused by `module_function`. `module_function` makes YARD register one definition twice: as a public class method and as a private instance method. One of the two is built with `CodeObjects::Base#copy_to`, which assigns it a normalized copy of the authored docstring that preserves content but not layout. The normalized copy drops the blank lines between tags and folds in tags inherited from the enclosing namespace, so a correctly separated docstring was reported as `description -> api, api -> param, param -> return`. Both validators now lint the half whose docstring YARD read from source and skip the normalized copy. A genuinely unseparated `module_function` method is still reported, exactly once.
+- **[Bugfix]** `Tags/TagSeparator` and `Tags/TagGroupSeparator` now report a docstring once however many objects YARD generates from it. An `attr_accessor` registers a reader and a writer sharing one comment block, so a layout offense in that comment was reported once for each of them. `Results::Aggregate` did not collapse the pair because each message names its own method. Both validators now report each docstring location once, using the `duplicate_docstring?` helper the base validator already provides.
+
 ## 1.11.0 (2026-08-11)
 - [Maintenance] Re-release of `1.10.3` as `1.11.0` due to new features being present.
 

data/README.md

@@ -143,6 +143,14 @@ yard-lint lib/ --only Tags/Order,Documentation/UndocumentedObjects
 
 **Learn more:** [Advanced Usage Guide](https://github.com/mensfeld/yard-lint/wiki/Advanced-Usage)
 
+### Explain a Validator
+
+Print what a validator checks, its default severity, configuration options, and Bad/Good examples directly in the terminal - no need to open the wiki. The explanation is sourced from the validator's own YARD documentation.
+
+```bash
+yard-lint --explain Tags/TypeSyntax
+```
+
 ### Lint from stdin (LSP / Editor Integration)
 
 Pass source bytes directly without reading from disk. The `path` argument is still required - it governs config resolution, exclusion matching, and offense location reporting.
@@ -538,6 +546,7 @@ Diff Mode:
 
 Validators:
       --only VALIDATORS   Run only specified validators (comma-separated)
+      --explain VALIDATOR Explain what a validator checks and how to configure it
 
 Configuration Generation:
       --init              Generate .yard-lint.yml config file

data/bin/yard-lint

@@ -64,6 +64,10 @@ begin
     options[:only] = validators.split(',').map(&:strip)
   end
 
+  opts.on('--explain VALIDATOR', 'Explain what a validator checks and how to configure it') do |validator|
+    options[:explain] = validator
+  end
+
   opts.separator ''
   opts.separator 'Other options:'
 
@@ -112,6 +116,7 @@ begin
     puts '  yard-lint lib/                                 # Lint all files in lib/'
     puts '  yard-lint --only Tags/TypeSyntax lib/          # Run only one validator on lib/'
     puts '  yard-lint --only Tags/Order,Tags/TypeSyntax    # Run specific validators'
+    puts '  yard-lint --explain Tags/TypeSyntax            # Explain what a validator checks'
     puts '  yard-lint --diff main                          # Lint files changed since main branch'
     puts '  yard-lint --staged                             # Lint only staged files'
     puts '  yard-lint --changed                            # Lint only uncommitted files'
@@ -133,6 +138,33 @@ rescue OptionParser::ParseError => e
   exit 1
 end
 
+# Report one or more unknown validator names with "did you mean" suggestions,
+# the full list of available validators, and a pointer to --explain. Shared by
+# --only and --explain so the two stay consistent.
+report_unknown_validators = lambda do |names|
+  checker = DidYouMean::SpellChecker.new(dictionary: Yard::Lint::ConfigLoader::ALL_VALIDATORS)
+  messages = names.map do |name|
+    suggestions = checker.correct(name)
+    suggestions.any? ? "  #{name} (did you mean: #{suggestions.first}?)" : "  #{name}"
+  end
+  puts 'Error: Unknown validator(s):'
+  puts messages.join("\n")
+  puts "\nAvailable validators:"
+  Yard::Lint::ConfigLoader::ALL_VALIDATORS.each { |v| puts "  #{v}" }
+  puts "\nRun `yard-lint --explain VALIDATOR` to see what a validator checks."
+end
+
+# Handle --explain flag (early exit; needs no config or path)
+if options[:explain]
+  name = options[:explain]
+  unless Yard::Lint::ConfigLoader::ALL_VALIDATORS.include?(name)
+    report_unknown_validators.call([name])
+    exit 1
+  end
+  puts Yard::Lint::Explainer.call(name)
+  exit 0
+end
+
 # Disambiguate `--diff PATH`. `--diff [REF]` takes an optional argument, so
 # `yard-lint --diff lib/` makes OptionParser consume `lib/` as the REF, leaving
 # no PATH (the run then tries `git diff lib/...HEAD` and fails). When the --diff
@@ -260,15 +292,7 @@ config.min_coverage = options[:min_coverage] if options[:min_coverage]
 if options[:only]
   unknown = options[:only] - Yard::Lint::ConfigLoader::ALL_VALIDATORS
   if unknown.any?
-    checker = DidYouMean::SpellChecker.new(dictionary: Yard::Lint::ConfigLoader::ALL_VALIDATORS)
-    messages = unknown.map do |name|
-      suggestions = checker.correct(name)
-      suggestions.any? ? "  #{name} (did you mean: #{suggestions.first}?)" : "  #{name}"
-    end
-    puts "Error: Unknown validator(s):"
-    puts messages.join("\n")
-    puts "\nAvailable validators:"
-    Yard::Lint::ConfigLoader::ALL_VALIDATORS.each { |v| puts "  #{v}" }
+    report_unknown_validators.call(unknown)
     exit 1
   end
   config.only_validators = options[:only]

data/lib/yard/lint/explainer.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Renders a human-readable explanation of a single validator for the terminal.
+    #
+    # The explanation is sourced from the validator's own YARD documentation block
+    # (the module file, e.g. `validators/tags/type_syntax.rb`) - yard-lint reads its
+    # own YARD docs to explain itself. This keeps the explanation next to the code it
+    # documents rather than in a separate file that can drift, and gives the doc
+    # blocks a standing reason to stay accurate.
+    #
+    # @example
+    #   puts Yard::Lint::Explainer.call("Tags/TypeSyntax")
+    class Explainer
+      # Keys in a validator's defaults that are surfaced in the header rather than
+      # listed as tunable configuration options.
+      META_KEYS = %w[Enabled Severity].freeze
+
+      # Build the explanation for a validator.
+      # @param name [String] validator name (e.g. 'Tags/TypeSyntax')
+      # @return [String] formatted, terminal-ready explanation
+      def self.call(name)
+        new(name).call
+      end
+
+      # @param name [String] validator name (e.g. 'Tags/TypeSyntax')
+      def initialize(name)
+        @name = name
+      end
+
+      # @return [String] formatted, terminal-ready explanation
+      # @raise [ArgumentError] if name is not a known validator
+      def call
+        unless ConfigLoader::ALL_VALIDATORS.include?(@name)
+          raise ArgumentError, "Unknown validator: #{@name.inspect}"
+        end
+
+        [header, body].compact.join("\n")
+      end
+
+      private
+
+      # @return [String] the metadata header (name, defaults) for the validator
+      def header
+        lines = [@name.to_s]
+        lines << "  Enabled by default: #{default_config.validator_enabled?(@name)}"
+        lines << "  Default severity:   #{default_config.validator_severity(@name)}"
+
+        config_keys = validator_defaults.keys - META_KEYS
+        lines << "  Configuration keys: #{config_keys.join(', ')}" if config_keys.any?
+        lines.join("\n")
+      end
+
+      # @return [String] the documentation body (description, config, examples)
+      def body
+        doc = documentation
+        return raw_comment_fallback if doc.nil?
+
+        sections = ["\n#{doc[:description]}"]
+        sections << render_examples(doc[:examples]) if doc[:examples].any?
+        sections.join("\n")
+      end
+
+      # @param examples [Array(String, String)] pairs of example label and code
+      # @return [String] the rendered "Examples:" section
+      def render_examples(examples)
+        rendered = examples.map do |name, text|
+          code = text.each_line.map { |line| "    #{line}" }.join
+          "  #{name}\n#{code}".rstrip
+        end
+        "\nExamples:\n#{rendered.join("\n\n")}"
+      end
+
+      # A config carrying only built-in defaults (no user overrides), used as the
+      # authoritative source for the validator's default enabled state and
+      # severity so the header never drifts from how the linter actually resolves
+      # them (see Config#validator_enabled? / #validator_severity).
+      # @return [Config] the defaults-only config
+      def default_config
+        @default_config ||= Config.new
+      end
+
+      # @return [Hash] the validator's default configuration
+      def validator_defaults
+        config = ConfigLoader.validator_config(@name)
+        config&.defaults || {}
+      end
+
+      # Parse the validator's module file with YARD and extract its description
+      # and examples. Runs in an isolated registry - any objects a caller parsed
+      # before us are saved and restored - so explaining a validator never
+      # clobbers the shared YARD::Registry.
+      # @return [Hash, nil] { description: String, examples: Array((String, String)) }
+      #   or nil if no docstring is available
+      def documentation
+        path = source_path
+        return nil unless path && File.exist?(path)
+
+        saved = YARD::Registry.all
+        YARD::Registry.clear
+        begin
+          YARD.parse_string(File.read(path))
+          docstring = YARD::Registry.at(object_path)&.docstring
+          return nil if docstring.nil? || docstring.to_s.strip.empty?
+
+          {
+            description: docstring.to_s,
+            examples: docstring.tags(:example).map { |tag| [tag.name, tag.text.to_s] }
+          }
+        ensure
+          YARD::Registry.clear
+          saved.each { |object| YARD::Registry.register(object) }
+        end
+      end
+
+      # @return [String] the fully-qualified code object path (e.g.
+      #   'Yard::Lint::Validators::Tags::TypeSyntax')
+      def object_path
+        category, validator = @name.split('/')
+        "Yard::Lint::Validators::#{category}::#{validator}"
+      end
+
+      # Resolve the validator module file from its name by inverting the casing
+      # convention used in ConfigLoader.discover_validators.
+      # @return [String] absolute path to the validator module file
+      def source_path
+        category, validator = @name.split('/')
+        File.join(__dir__, 'validators', snake_case(category), "#{snake_case(validator)}.rb")
+      end
+
+      # Convert a PascalCase segment to snake_case (inverse of the
+      # `split('_').map(&:capitalize).join` used during discovery).
+      # @param string [String] PascalCase name (e.g. 'TypeSyntax')
+      # @return [String] snake_case name (e.g. 'type_syntax')
+      def snake_case(string)
+        string.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      # Defensive fallback: print the raw leading comment block from the module
+      # file when YARD yields no docstring. Every validator currently ships a doc
+      # block, so this should not normally be reached.
+      # @return [String, nil] the raw comment text, or nil if it cannot be read
+      def raw_comment_fallback
+        path = source_path
+        return nil unless path && File.exist?(path)
+
+        comment = []
+        File.foreach(path) do |line|
+          stripped = line.strip
+          if stripped.start_with?('#')
+            comment << stripped.sub(/\A#\s?/, '')
+          elsif stripped.start_with?('module ') && comment.any?
+            break
+          else
+            comment.clear
+          end
+        end
+        comment.any? ? "\n#{comment.join("\n")}" : nil
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/base.rb

@@ -110,6 +110,66 @@ module Yard
           !@scanned_docstrings.add?(key)
         end
 
+        # Whether the object is a synthesized copy whose docstring has been
+        # normalized and should not be linted.
+        #
+        # `module_function` makes YARD register one definition twice: as a public
+        # class method and as a private instance method.
+        #
+        # One of the two is built with `CodeObjects::Base#copy_to` which assigns a
+        # docstring which is a normalized copy of the original, authored docstring
+        # that preserves content but not layout.
+        #
+        # The normalized docstring drops the blank lines between tags, moves param
+        # types ahead of param names, and folds in tags inherited from the enclosing
+        # namespace (such as an api tag). Linting the normalized docstring reports
+        # layout offenses against text no one wrote.
+        #
+        # The authored docstring is the one YARD tracks back to a range of source
+        # lines.
+        #
+        # For `module_function def name` neither the original object nor its copy
+        # carries a line range. For this form, the instance method holds the original
+        # docstring (YARD::Handlers::Ruby::ModuleFunctionHandler copies it to the
+        # class method).
+        #
+        # @param object [YARD::CodeObjects::Base] the code object to check
+        # @return [Boolean] true if the object's docstring is a normalized copy
+        def module_function_copy?(object)
+          return false unless object.type == :method
+          # Checked before the twin lookup, which scans the namespace's children:
+          # an object YARD tracked back to source lines is authored, whatever it
+          # is paired with, and most objects are
+          return false if object.docstring.line_range
+
+          twin = module_function_twin(object)
+          return false unless twin
+          return true if twin.docstring.line_range
+
+          object.scope == :class
+        end
+
+        # Finds the other object registered for a module_function definition.
+        # @param object [YARD::CodeObjects::Base] one half of the pair
+        # @return [YARD::CodeObjects::MethodObject, nil] the other half, or nil
+        #   when the object does not come from module_function
+        def module_function_twin(object)
+          return nil unless object.respond_to?(:scope)
+
+          twin = object.namespace.child(
+            name: object.name,
+            scope: (object.scope == :class) ? :instance : :class
+          )
+
+          return nil unless twin
+          return nil unless twin.file == object.file && twin.line == object.line
+          # Both halves point at the same definition, but only the class method
+          # is flagged as a module function by YARD.
+          return nil unless [object, twin].any? { |o| o.respond_to?(:module_function?) && o.module_function? }
+
+          twin
+        end
+
         # Converts a zero-based line offset within a docstring's text into an
         # absolute line number in the source file, so offenses can point at
         # the offending documentation line instead of the definition line.

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

@@ -24,6 +24,14 @@ module Yard
               # is_alias? exists only on method objects; on namespace objects
               # YARD's method_missing raises NameError, so guard by type first
               return if object.type == :method && object.is_alias?
+              # The rebuilt half of a module_function pair carries no authored
+              # layout, only YARD's normalization of it. Checked before
+              # duplicate_docstring? so the normalized half never claims the
+              # location its authored twin needs
+              return if module_function_copy?(object)
+              # Objects sharing one comment block (an attr_accessor's reader and
+              # writer) would otherwise report the same offense once each
+              return if duplicate_docstring?(object)
 
               docstring = object.docstring.all
               return if docstring.nil? || docstring.empty?

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

@@ -26,6 +26,14 @@ module Yard
               # is_alias? exists only on method objects; on namespace objects
               # YARD's method_missing raises NameError, so guard by type first
               return if object.type == :method && object.is_alias?
+              # The rebuilt half of a module_function pair carries no authored
+              # layout, only YARD's normalization of it. Checked before
+              # duplicate_docstring? so the normalized half never claims the
+              # location its authored twin needs
+              return if module_function_copy?(object)
+              # Objects sharing one comment block (an attr_accessor's reader and
+              # writer) would otherwise report the same offense once each
+              return if duplicate_docstring?(object)
 
               docstring = object.docstring.all
               return if docstring.nil? || docstring.empty?

data/lib/yard/lint/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -62,6 +62,7 @@ files:
 - lib/yard/lint/executor/query_executor.rb
 - lib/yard/lint/executor/result_collector.rb
 - lib/yard/lint/executor/warning_dispatcher.rb
+- lib/yard/lint/explainer.rb
 - lib/yard/lint/ext/irb_notifier_shim.rb
 - lib/yard/lint/formatters/progress.rb
 - lib/yard/lint/git.rb
@@ -327,7 +328,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: YARD documentation linter and validator
 test_files: []