yard-lint 1.6.1 → 1.7.0

data/lib/yard/lint/results/aggregate.rb

@@ -26,9 +26,14 @@ module Yard
         end
 
         # Get all offenses from all validators
-        # @return [Array<Hash>] flattened array of all offenses
+        # Identical offenses are reported once: objects sharing one docstring
+        # (e.g. the reader and writer generated by attr_accessor) produce the
+        # same offense for each generated method
+        # @return [Array<Hash>] flattened array of unique offenses
         def offenses
-          @results.flat_map(&:offenses)
+          @offenses ||= @results.flat_map(&:offenses).uniq do |offense|
+            offense.values_at(:validator, :name, :location, :location_line, :message)
+          end
         end
 
         # Total number of offenses
@@ -78,10 +83,11 @@ module Yard
         # @return [Integer] 0 for success, 1 for failure
         def exit_code
           # Check minimum coverage requirement first
-          if @config&.min_coverage &&
-             documentation_coverage &&
-             documentation_coverage[:coverage] < @config.min_coverage
-            return 1
+          if @config&.min_coverage
+            coverage = documentation_coverage
+            # Fail safe: if a minimum is required but coverage could not be
+            # determined (e.g. the YARD stats subprocess failed), do not pass.
+            return 1 if coverage.nil? || coverage[:coverage] < @config.min_coverage
           end
 
           return 0 if offenses.empty?
@@ -95,7 +101,9 @@ module Yard
           when SEVERITY_WARNING
             (statistics[:error] + statistics[:warning]).positive? ? 1 : 0
           when SEVERITY_CONVENTION
-            offenses.any? ? 1 : 0
+            # Exclude 'never'-severity offenses, which are meant to run without
+            # ever failing the build (they are also omitted from #statistics).
+            (statistics[:error] + statistics[:warning] + statistics[:convention]).positive? ? 1 : 0
           else
             0
           end

data/lib/yard/lint/stats_calculator.rb

@@ -20,6 +20,10 @@ module Yard
         return default_stats if files.empty?
 
         raw_stats = run_yard_stats_query
+        # nil means the YARD subprocess failed - return nil (coverage unknown)
+        # rather than default_stats, which would falsely report 100% coverage
+        # and let a MinCoverage gate pass.
+        return nil if raw_stats.nil?
         return default_stats if raw_stats.empty?
 
         parsed_stats = parse_stats_output(raw_stats)
@@ -52,8 +56,10 @@ module Yard
 
             stdout, _stderr, status = Open3.capture3(cmd)
 
-            # Return empty string if YARD command fails
-            return '' unless status.exitstatus.zero?
+            # Return nil if the YARD command fails (non-zero exit, or killed by
+            # a signal so exitstatus is nil) - distinct from genuinely empty
+            # output, so coverage is reported as unknown rather than 100%.
+            return nil unless status.exitstatus&.zero?
 
             stdout
           end

data/lib/yard/lint/templates/default_config.yml

@@ -44,6 +44,12 @@ Documentation/UndocumentedMethodArguments:
   Description: 'Checks for method parameters without @param tags.'
   Enabled: true
   Severity: warning
+  # Match each parameter to a @param tag by name (catches a misnamed @param).
+  # Set to false to fall back to a lenient count-only comparison.
+  CheckParameterNames: true
+  # Opt-in: skip methods with no documentation at all (reported by
+  # Documentation/UndocumentedObjects) instead of flagging them here too.
+  SkipFullyUndocumented: false
   # AllowedParentClasses:
   #   - StandardError
   # AllowedMethods: skip @param checks for specific methods (exact name, name/arity, /regex/)
@@ -142,6 +148,13 @@ Tags/InvalidTypes:
     - param
     - option
     - return
+    - yieldreturn
+    - yieldparam
+    - raise
+  # Opt-in: flag CamelCase type names that are neither loaded Ruby constants
+  # nor defined in the analyzed codebase (catches typos like `Strng`). Off by
+  # default because types from un-analyzed dependencies would also be flagged.
+  StrictConstantNames: false
 
 Tags/TypeSyntax:
   Description: 'Validates YARD type syntax using YARD parser.'
@@ -152,6 +165,8 @@ Tags/TypeSyntax:
     - option
     - return
     - yieldreturn
+    - yieldparam
+    - raise
 
 Tags/MeaninglessTag:
   Description: 'Detects @param/@option tags on classes, modules, or constants.'
@@ -180,6 +195,8 @@ Tags/CollectionType:
     - option
     - return
     - yieldreturn
+    - yieldparam
+    - raise
 
 Tags/TagTypePosition:
   Description: 'Validates type annotation position in tags.'
@@ -210,6 +227,10 @@ Tags/ExampleSyntax:
   Description: 'Validates Ruby syntax in @example tags.'
   Enabled: true
   Severity: warning
+  # Opt-in: skip @example blocks that are interactive console transcripts
+  # (irb/pry sessions, their `=>` output, or shell `$` prompts) rather than
+  # runnable Ruby. Off by default so a real syntax error is not hidden.
+  SkipNonRuby: false
 
 Tags/ExampleStyle:
   Description: 'Validates code style in @example tags using RuboCop/StandardRB.'
@@ -258,14 +279,20 @@ Tags/InformalNotation:
   Severity: warning
   CaseSensitive: false
   RequireStartOfLine: true
+  # Opt-in: also skip 4-space/tab indented Markdown code blocks (not just
+  # fenced ``` blocks). Off by default - indented text is also used for list
+  # continuations and wrapped prose, which would then be skipped too.
+  SkipIndentedCodeBlocks: false
   Patterns:
     Note: '@note'
+    IMPORTANT: '@note'
+    Important: '@note'
     Todo: '@todo'
     TODO: '@todo'
     FIXME: '@todo'
     See: '@see'
     See also: '@see'
-    Warning: '@deprecated'
+    Warning: '@note'
     Deprecated: '@deprecated'
     Author: '@author'
     Version: '@version'
@@ -284,6 +311,7 @@ Tags/NonAsciiType:
     - return
     - yieldreturn
     - yieldparam
+    - raise
 
 Tags/TagGroupSeparator:
   Description: 'Enforces blank line separators between different YARD tag groups.'
@@ -313,6 +341,11 @@ Tags/ForbiddenTags:
   # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
 
 # Warnings validators - catches YARD parser errors
+Warnings/SyntaxError:
+  Description: 'Detects Ruby files YARD cannot parse (syntax errors).'
+  Enabled: true
+  Severity: error
+
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'
   Enabled: true

data/lib/yard/lint/templates/strict_config.yml

@@ -48,6 +48,11 @@ Documentation/UndocumentedMethodArguments:
   Description: 'Checks for method parameters without @param tags.'
   Enabled: true
   Severity: error
+  # Match each parameter to a @param tag by name (catches a misnamed @param).
+  CheckParameterNames: true
+  # Opt-in: skip methods with no documentation at all (reported by
+  # Documentation/UndocumentedObjects) instead of flagging them here too.
+  SkipFullyUndocumented: false
   # AllowedParentClasses:
   #   - StandardError
   # AllowedMethods: skip @param checks for specific methods (exact name, name/arity, /regex/)
@@ -146,6 +151,13 @@ Tags/InvalidTypes:
     - param
     - option
     - return
+    - yieldreturn
+    - yieldparam
+    - raise
+  # The strict preset opts in: flag CamelCase type names that are neither loaded
+  # Ruby constants nor defined in the analyzed codebase (catches typos). Add any
+  # legitimate dependency types to ExtraTypes to silence false positives.
+  StrictConstantNames: true
 
 Tags/TypeSyntax:
   Description: 'Validates YARD type syntax using YARD parser.'
@@ -156,6 +168,8 @@ Tags/TypeSyntax:
     - option
     - return
     - yieldreturn
+    - yieldparam
+    - raise
 
 Tags/MeaninglessTag:
   Description: 'Detects @param/@option tags on classes, modules, or constants.'
@@ -184,6 +198,8 @@ Tags/CollectionType:
     - option
     - return
     - yieldreturn
+    - yieldparam
+    - raise
 
 Tags/TagTypePosition:
   Description: 'Validates type annotation position in tags.'
@@ -214,6 +230,10 @@ Tags/ExampleSyntax:
   Description: 'Validates Ruby syntax in @example tags.'
   Enabled: true
   Severity: error
+  # Opt-in: skip @example blocks that are interactive console transcripts
+  # (irb/pry sessions, their `=>` output, or shell `$` prompts) rather than
+  # runnable Ruby. Off by default so a real syntax error is not hidden.
+  SkipNonRuby: false
 
 Tags/ExampleStyle:
   Description: 'Validates code style in @example tags using RuboCop/StandardRB.'
@@ -254,6 +274,7 @@ Tags/RedundantParamDescription:
     IdPattern: true
     DirectionalDate: true
     TypeGeneric: true
+    ArticleParamPhrase: true
 
 Tags/InformalNotation:
   Description: 'Detects informal tag notation patterns like "Note:" instead of @note.'
@@ -261,14 +282,20 @@ Tags/InformalNotation:
   Severity: error
   CaseSensitive: false
   RequireStartOfLine: true
+  # Opt-in: also skip 4-space/tab indented Markdown code blocks (not just
+  # fenced ``` blocks). Off by default - indented text is also used for list
+  # continuations and wrapped prose, which would then be skipped too.
+  SkipIndentedCodeBlocks: false
   Patterns:
     Note: '@note'
+    IMPORTANT: '@note'
+    Important: '@note'
     Todo: '@todo'
     TODO: '@todo'
     FIXME: '@todo'
     See: '@see'
     See also: '@see'
-    Warning: '@deprecated'
+    Warning: '@note'
     Deprecated: '@deprecated'
     Author: '@author'
     Version: '@version'
@@ -287,6 +314,7 @@ Tags/NonAsciiType:
     - return
     - yieldreturn
     - yieldparam
+    - raise
 
 Tags/TagGroupSeparator:
   Description: 'Enforces blank line separators between different YARD tag groups.'
@@ -316,6 +344,11 @@ Tags/ForbiddenTags:
   # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
 
 # Warnings validators - catches YARD parser errors
+Warnings/SyntaxError:
+  Description: 'Detects Ruby files YARD cannot parse (syntax errors).'
+  Enabled: true
+  Severity: error
+
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'
   Enabled: true

data/lib/yard/lint/todo_generator.rb

@@ -13,9 +13,12 @@ module Yard
         # @param config [Config] yard-lint configuration object with validator settings
         # @param force [Boolean] whether to overwrite existing todo file if present
         # @param exclude_limit [Integer] minimum files in directory before grouping into wildcard patterns
+        # @param config_path [String, nil] config file to link the todo into
+        #   (defaults to .yard-lint.yml in the current directory)
         # @return [Hash] result with :message, :offense_count, :validator_count
-        def generate(path:, config:, force: false, exclude_limit: DEFAULT_EXCLUDE_LIMIT)
-          new(path: path, config: config, force: force, exclude_limit: exclude_limit).generate
+        def generate(path:, config:, force: false, exclude_limit: DEFAULT_EXCLUDE_LIMIT, config_path: nil)
+          new(path: path, config: config, force: force, exclude_limit: exclude_limit,
+              config_path: config_path).generate
         end
       end
 
@@ -24,13 +27,14 @@ module Yard
       # @param config [Config] yard-lint configuration object
       # @param force [Boolean] whether to overwrite existing todo file
       # @param exclude_limit [Integer] minimum files before grouping into patterns
-      def initialize(path:, config:, force:, exclude_limit:)
+      # @param config_path [String, nil] config file to link the todo into
+      def initialize(path:, config:, force:, exclude_limit:, config_path: nil)
         @path = path
         @config = config
         @force = force
         @exclude_limit = exclude_limit
         @todo_path = File.join(Dir.pwd, '.yard-lint-todo.yml')
-        @config_path = File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
+        @config_path = config_path || File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
       end
 
       # Generate the .yard-lint-todo.yml file with exclusions for current violations
@@ -93,6 +97,12 @@ module Yard
           next unless @config.validator_enabled?(validator_name)
 
           validator_result = result_builder.build(validator_name, raw_results)
+          next unless validator_result
+
+          # Apply per-validator Exclude patterns (and drop no-location offenses)
+          # exactly as a normal run does, so the baseline does not silence files
+          # that are already excluded.
+          validator_result = runner.send(:filter_result_offenses, validator_name, validator_result)
           next unless validator_result && validator_result.offenses.any?
 
           # Extract file paths from offenses, skipping those without a location
@@ -206,17 +216,28 @@ module Yard
       # Update existing config file to add inherit_from todo file
       # @return [void]
       def update_existing_config
-        config_yaml = YAML.load_file(@config_path) || {}
-        inherit_from = Array(config_yaml['inherit_from'] || [])
-
-        # Add todo file to inherit_from if not already present
-        unless inherit_from.include?('.yard-lint-todo.yml')
-          inherit_from.unshift('.yard-lint-todo.yml')
-          config_yaml['inherit_from'] = inherit_from
+        config_yaml = ConfigLoader.load_yaml_file(@config_path)
+        return if Array(config_yaml['inherit_from']).include?('.yard-lint-todo.yml')
+
+        raw = File.read(@config_path)
+
+        # Edit the file textually rather than round-tripping through to_yaml,
+        # which would strip every comment and reformat the user's config.
+        updated =
+          if config_yaml.key?('inherit_from') && raw.match?(/^inherit_from:[ \t]*$/)
+            # Existing block list - prepend our entry as the first item.
+            raw.sub(/^inherit_from:[ \t]*$\n/) { "#{Regexp.last_match(0)}  - .yard-lint-todo.yml\n" }
+          elsif config_yaml.key?('inherit_from')
+            # Existing inline/array form (rare) - fall back to a structured
+            # rewrite; comments cannot be preserved in this case.
+            config_yaml['inherit_from'] = ['.yard-lint-todo.yml'] + Array(config_yaml['inherit_from'])
+            config_yaml.to_yaml
+          else
+            # No inherit_from yet - prepend a block, preserving the file verbatim.
+            "inherit_from:\n  - .yard-lint-todo.yml\n\n#{raw}"
+          end
 
-          # Write updated config
-          File.write(@config_path, config_yaml.to_yaml)
-        end
+        File.write(@config_path, updated)
       end
 
       # Create a minimal config file that inherits from todo file

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

@@ -97,6 +97,41 @@ module Yard
           tags
         end
 
+        # Tracks docstring locations already processed by this validator
+        # instance. Objects generated from a single comment block (e.g. the
+        # reader and writer created by attr_accessor) share one docstring;
+        # content-scanning validators use this to report each docstring once.
+        # @param object [YARD::CodeObjects::Base] the code object to check
+        # @return [Boolean] true if this object's docstring was already seen
+        def duplicate_docstring?(object)
+          @scanned_docstrings ||= Set.new
+          key = [object.file, object.docstring.line_range&.first || object.line]
+
+          !@scanned_docstrings.add?(key)
+        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.
+        # @param object [YARD::CodeObjects::Base] the documented object
+        # @param line_offset [Integer] zero-based offset within the docstring text
+        # @return [Integer] absolute source line number
+        def docstring_line(object, line_offset)
+          start_line = object.docstring.line_range&.first || object.line
+
+          start_line + line_offset
+        end
+
+        # Returns the tag that actually carries a tag's types and description.
+        # For most tags that is the tag itself, but @option tags wrap their
+        # data in a nested pair tag - tag.types and tag.text are nil on the
+        # OptionTag itself, with the documented option living on tag.pair.
+        # @param tag [YARD::Tags::Tag] tag whose data holder should be resolved
+        # @return [YARD::Tags::Tag] the tag holding types/text data
+        def tag_data(tag)
+          tag.respond_to?(:pair) && tag.pair ? tag.pair : tag
+        end
+
         # Checks whether the object's enclosing class (or the object itself if it is
         # a class) has a superclass that appears in the validator's AllowedParentClasses
         # configuration list. When true, validators skip the object so that classes
@@ -236,7 +271,10 @@ module Yard
 
           return defaults[key] unless validator_name
 
-          config.validator_config(validator_name, key) || defaults[key]
+          value = config.validator_config(validator_name, key)
+          # A nil? check (not ||) so that explicitly configured false values
+          # are honored instead of falling back to a truthy default
+          value.nil? ? defaults[key] : value
         end
       end
     end

data/lib/yard/lint/validators/documentation/blank_line_before_definition/validator.rb

@@ -50,8 +50,11 @@ module Yard
                 if stripped.empty?
                   blank_count += 1
                 elsif stripped.start_with?('#')
-                  # Skip Ruby magic comments - they're not YARD documentation
-                  next if magic_comment?(stripped)
+                  # Skip lines that are not YARD documentation: magic comments,
+                  # shebangs, tool sigils/directives (Sorbet, RuboCop, Standard),
+                  # and bare `#` separators. Treating them as a doc block caused
+                  # spurious blank-line offenses for undocumented definitions.
+                  next if non_documentation_comment?(stripped)
 
                   has_doc_block = true
                   break
@@ -72,6 +75,18 @@ module Yard
               line.match?(/^#\s*(frozen[_-]string[_-]literal|encoding|warn[_-]indent|shareable[_-]constant[_-]value)\s*:/i)
             end
 
+            # Check if a comment line is not YARD documentation (magic comment,
+            # shebang, tool sigil/directive, or a bare `#` separator).
+            # @param line [String] stripped comment line
+            # @return [Boolean] true if the line should not count as documentation
+            def non_documentation_comment?(line)
+              magic_comment?(line) ||
+                line.start_with?('#!') ||                          # shebang
+                line.match?(/\A#\s*(rubocop|standard):/i) ||       # linter directives
+                line.match?(/\A#\s*typed:/i) ||                    # Sorbet sigil
+                line.match?(/\A#+\s*\z/)                           # bare # separator
+            end
+
             # Check if the given pattern is enabled in configuration
             # @param violation_type [String] 'single' or 'orphaned'
             # @return [Boolean] whether the pattern is enabled

data/lib/yard/lint/validators/documentation/empty_comment_line/validator.rb

@@ -33,8 +33,11 @@ module Yard
                 stripped = line.strip
 
                 if stripped.empty? && comment_end.nil?
-                  # Skip empty lines before finding comment block
-                  next
+                  # A blank line between the definition and any comment above
+                  # means there is no attached docstring (YARD only attaches a
+                  # comment immediately above the definition), so stop scanning -
+                  # otherwise a detached file header is mistaken for the doc.
+                  break
                 elsif stripped.start_with?('#')
                   comment_end ||= i
                   comment_start = i

data/lib/yard/lint/validators/documentation/line_length/validator.rb

@@ -23,6 +23,7 @@ module Yard
 
               line_range = object.docstring.line_range
               return unless line_range
+              return if duplicate_docstring?(object)
 
               max_length = config_or_default('MaxLength').to_i
               source_lines = cached_lines(object.file)

data/lib/yard/lint/validators/documentation/markdown_syntax/validator.rb

@@ -18,26 +18,30 @@ module Yard
             def in_process_query(object, collector)
               docstring_text = object.docstring.to_s
               return if docstring_text.empty?
+              return if duplicate_docstring?(object)
 
               errors = []
 
-              # Check for unclosed backticks
-              backtick_count = docstring_text.scan(/`/).count
-              errors << 'unclosed_backtick' if backtick_count.odd?
+              # Check for unclosed inline backticks, ignoring fenced code blocks
+              # (``` ... ```): their fence characters and contents are not
+              # inline-code markers and otherwise inflate the count.
+              errors << 'unclosed_backtick' if inline_backtick_count(docstring_text).odd?
 
               # Check for unclosed code blocks
               code_block_count = docstring_text.scan(/^```/).count
               errors << 'unclosed_code_block' if code_block_count.odd?
 
-              # Check for unclosed bold markers (excluding code sections)
-              non_code_text = docstring_text.gsub(/`[^`]*`/, '')
-              bold_count = non_code_text.scan(/\*\*/).count
-              errors << 'unclosed_bold' if bold_count.odd?
+              # Check for unclosed bold markers, ignoring fenced code blocks and
+              # inline code spans (their contents are code, not markdown) as well
+              # as `**` runs surrounded by whitespace, which cannot delimit
+              # CommonMark emphasis (e.g. the exponent operator in `x ** y`).
+              errors << 'unclosed_bold' if bold_marker_count(docstring_text).odd?
 
-              # Check for invalid list markers
+              # Check for invalid list markers, reported with their absolute
+              # source line rather than a docstring-relative index
               docstring_text.lines.each_with_index do |line, line_idx|
                 stripped = line.strip
-                errors << "invalid_list_marker:#{line_idx + 1}" if stripped.match?(/^[•·]/)
+                errors << "invalid_list_marker:#{docstring_line(object, line_idx)}" if stripped.match?(/^[•·]/)
               end
 
               return if errors.empty?
@@ -45,6 +49,59 @@ module Yard
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
               collector.puts errors.join('|')
             end
+
+            private
+
+            # Counts inline backticks, skipping fenced code blocks (``` ... ```)
+            # entirely - their fence characters and contents are not inline-code
+            # markers.
+            # @param text [String] the docstring text
+            # @return [Integer] number of inline backticks outside fenced blocks
+            def inline_backtick_count(text)
+              in_fence = false
+              count = 0
+              text.each_line do |line|
+                if line.strip.start_with?('```')
+                  in_fence = !in_fence
+                  next
+                end
+                next if in_fence
+
+                count += line.count('`')
+              end
+              count
+            end
+
+            # Counts `**` emphasis markers, skipping fenced code blocks and
+            # inline code spans entirely. A `**` run is only counted when it
+            # abuts a non-whitespace character on at least one side, since a run
+            # padded by whitespace on both sides can neither open nor close
+            # CommonMark emphasis - this excludes the exponent operator (`x ** y`)
+            # without dropping genuine `**bold**` markers.
+            # @param text [String] the docstring text
+            # @return [Integer] number of bold markers that can delimit emphasis
+            def bold_marker_count(text)
+              in_fence = false
+              count = 0
+              text.each_line do |line|
+                if line.strip.start_with?('```')
+                  in_fence = !in_fence
+                  next
+                end
+                next if in_fence
+
+                non_code = line.gsub(/`[^`]*`/, '')
+                non_code.scan(/\*\*/) do
+                  match = Regexp.last_match
+                  # Peek at the surrounding characters without consuming them, so
+                  # adjacent runs like `**a**` (single-character bold) still pair up.
+                  before = match.pre_match[-1]
+                  after = match.post_match[0]
+                  count += 1 if before&.match?(/\S/) || after&.match?(/\S/)
+                end
+              end
+              count
+            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/missing_return/validator.rb

@@ -23,9 +23,9 @@ module Yard
               return unless object.is_explicit?
               return if parent_class_allowed?(object)
 
-              # Check if @return tag is missing
-              return_tag = object.tag(:return)
-              return unless return_tag.nil?
+              # Check if @return tag is missing; tags nested inside @overload
+              # blocks live on the overload's own docstring, so check those too
+              return unless all_typed_tags(object.docstring, %w[return]).empty?
 
               # Calculate arity (exclude splat and block parameters)
               arity = object.parameters.reject { |p| p[0].to_s.start_with?('*', '&') }.size