yard-lint 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3e167ca549d10a6391cdcee97de9e53356448146f58d045dbd7aed87466460c
-  data.tar.gz: 17197fe60701c4b0f93deefb4b9b933e7deba9eaa9499d201908649b09da1019
+  metadata.gz: '04219019cfc32c314c95eea949d26bd01a92c00cecbcffd44149ed537a09d148'
+  data.tar.gz: 563bc04039db71d71510bfcd1feba0f7f2bc01b025807f22d97f6085e5a30282
 SHA512:
-  metadata.gz: f274aa4a55a41ab329ba44a6c76d4d2c0c9a431ea8da8a2ded67ee2208adec3cf7a658d275fc5ef843511ddb23dfdae96575dee565cd7435b93330af614ef4b0
-  data.tar.gz: ad921b1b3156088cbaeaf760773bf1d6f947759d7b29555cb2133586d5ccf12f1b41f98968598bf3ed21e6b98755727b835088f05d760d131bc081e9adffea8a
+  metadata.gz: 0f7856c26319046238cfd2fbf9515f0d21d0f50915df9e14e92971dc7c3555d028e4e83a267f0385b96a9453624b7f8b4fc209f2f609bb1044abda4516c0ac21
+  data.tar.gz: 3150e72089b7268bd63db4557eafc8dfc72ba7d398adc111442bf5f9f7534bb44284584074942dd8f5a10300cf5b44f9d11ec0e70dd0968fbd3326f8312853c4

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.8.0 (2026-06-17)
+- **[Feature]** Added `Documentation/UnderfilledLines` (opt-in, disabled by default, severity `convention`) - the inverse of `Documentation/LineLength`. Where `LineLength` flags comment lines that are too long, `UnderfilledLines` flags documentation prose that wraps *too early*: text that uses only a fraction of the available width and spills onto extra lines, wasting vertical space (common in AI-generated docs). It reports one offense per wasteful paragraph, and only when greedily re-wrapping the paragraph's words at `MaxLength` would genuinely use fewer lines, the widest line wastes at least `MinTrailingSpace` columns (default 20), and the paragraph is not deliberately broken one sentence/clause per line. Only the free-text description body is checked - YARD tags, fenced/indented code, lists, tables, headings, blockquotes and non-ASCII text are skipped. Because "this line should have been longer" is a stylistic judgement, the validator is deliberately conservative (biased toward not producing false positives) and stays opt-in; projects that use semantic line breaks (one sentence/clause per line, see sembr.org) are never flagged. Configurable via `MaxLength`, `MinTrailingSpace`, `MinParagraphLines`, `SentenceEndChars`, and `SkipNonAscii`.
+- **[Change]** Centralized source-file reading into `Validators::Base#cached_lines` (shared by `Documentation/LineLength` and `Documentation/UnderfilledLines` instead of being duplicated in each), and made it scrub invalid bytes so a non-UTF-8 source file can no longer raise `Encoding::CompatibilityError` while a validator matches a regex against its lines.
+
 ## 1.7.0 (2026-06-15)
 - **[Feature]** `Tags/ExampleSyntax` gained an opt-in `SkipNonRuby` option (default `false`). The validator compiles every `@example` body as Ruby, so an irb/pry session, its `=>` output, or a shell `$` transcript was reported as a syntax error. With `SkipNonRuby: true`, `@example` blocks that are interactive console transcripts are skipped. Off by default so a genuine syntax error in a normal example is not hidden.
 - **[Feature]** `Tags/InvalidTypes` gained an opt-in `StrictConstantNames` option (default `false`). The type check was deliberately lenient - any syntactically valid constant name was accepted - so a misspelled class name like `Strng` was never flagged, defeating the validator's headline use case. With `StrictConstantNames: true`, a CamelCase type that is neither a loaded Ruby constant nor resolvable in the analyzed codebase's YARD registry is reported. It stays off by default (types defined only in un-analyzed dependencies would otherwise be flagged - add those to `ExtraTypes`); the strict template (`--init --strict`) enables it. `Boolean` is now always accepted as a pseudo-type.

data/README.md

@@ -25,13 +25,13 @@ YARD-Lint validates your YARD documentation for:
 - **Parse Errors** - Files YARD cannot parse (syntax errors) are reported instead of silently skipped, so a run never passes over code that does not parse
 - **Code Examples** - Syntax validation in `@example` tags (with an opt-in skip for irb/pry/shell console transcripts), optional style validation with RuboCop/StandardRB
 - **Semantic Correctness** - Abstract methods with implementations, redundant descriptions
-- **Style & Formatting** - Empty comment lines, blank lines before definitions, informal notation patterns, tag group separators, configurable documentation line length (opt-in)
+- **Style & Formatting** - Empty comment lines, blank lines before definitions, informal notation patterns, tag group separators, and configurable documentation line length and line fill — flagging comment lines that are too long or prose that wraps before using the available width (both opt-in)
 - **Smart Suggestions** - "Did you mean" suggestions for typos in parameter names, tags, and configuration settings
 - **Configuration Safety** - Validates `.yard-lint.yml` for typos and invalid settings before processing
 - **Performance** - In-process YARD execution with shared registry (~10x faster than shell-based execution)
 - **Incremental Adoption** - `--auto-gen-config` generates a baseline todo file to adopt on legacy codebases without fixing everything first
 
-**See the complete list:** [All Features](https://github.com/mensfeld/yard-lint/wiki/Features) | [34 Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)
+**See the complete list:** [All Features](https://github.com/mensfeld/yard-lint/wiki/Features) | [36 Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)
 
 ## Installation
 
@@ -239,6 +239,11 @@ Documentation/UndocumentedObjects:
 Documentation/UndocumentedMethodArguments:
   Enabled: true
   Severity: warning
+  # Match each @param to a parameter by name (default). Catches a misnamed tag,
+  # not just a missing one. Set to false for a lenient count-only comparison.
+  CheckParameterNames: true
+  # Opt-in: skip methods with no documentation at all (left to UndocumentedObjects)
+  SkipFullyUndocumented: false
   # Skip @param checks for specific methods (exact name, name/arity, /regex/)
   AllowedMethods:
     - call            # service objects: call(args) is self-documenting
@@ -270,6 +275,9 @@ Tags/InvalidTypes:
   ExtraTypes:
     - generic          # Solargraph generic type parameter (lsegal/yard#1683)
     - MyNamespace::CustomType
+  # Opt-in: flag CamelCase types that are not loaded constants nor defined in the
+  # analyzed codebase (catches typos like `Strng`). Enabled by --init --strict.
+  StrictConstantNames: false
 
 # Opt-in: Require @return tags on all methods
 Documentation/MissingReturn:
@@ -287,6 +295,11 @@ Tags/ExampleStyle:
 Documentation/LineLength:
   Enabled: true
   MaxLength: 100
+
+# Opt-in: Flag documentation prose that wraps before using the available width
+Documentation/UnderfilledLines:
+  Enabled: true
+  MaxLength: 100
 ```
 
 **Key features:**
@@ -374,9 +387,38 @@ end
 
 Method calls like `Fiber.yield` and `yielder.yield` (Enumerator::Yielder) are not flagged - only the `yield` keyword triggers the check.
 
+## Encouraging full-width documentation (opt-in)
+
+`Documentation/LineLength` flags comment lines that are too *long*. `Documentation/UnderfilledLines` is its inverse: it flags documentation prose that wraps **too early** - text that uses only a fraction of the available width and spills onto extra lines, wasting vertical space. This pattern is especially common in AI-generated documentation.
+
+Enable it in `.yard-lint.yml`:
+
+```yaml
+Documentation/UnderfilledLines:
+  Enabled: true
+  MaxLength: 120          # target width (match your Documentation/LineLength)
+  MinTrailingSpace: 20    # only flag when the widest line wastes >= 20 columns
+```
+
+```ruby
+# Bad - prose wraps at ~55 columns when 120 are available
+# Processes the incoming payload and returns a normalized
+# hash that downstream consumers can rely on for routing.
+def process(payload); end
+
+# Good - prose fills the available width before wrapping
+# Processes the incoming payload and returns a normalized hash that downstream
+# consumers can rely on for routing.
+def process(payload); end
+```
+
+The validator reports one offense per wasteful paragraph and is deliberately conservative - it would rather miss a case than emit a false positive. It only looks at the free-text description body (tags, fenced/indented code, lists, tables, headings, blockquotes and non-ASCII text are left alone), and a paragraph is reported only when re-wrapping its words at `MaxLength` would genuinely use fewer lines.
+
+Unlike `LineLength` (which measures an objective property), "this line should have been longer" is a stylistic judgement. Projects that use **semantic line breaks** (one sentence or clause per line, see [sembr.org](https://sembr.org)) are never flagged - any paragraph whose non-final lines all end at a sentence boundary (`.?!:;`) is treated as intentional. Leave the validator off, or add `,` to `SentenceEndChars`, if that style is used heavily.
+
 ## Handling Non-Standard Types
 
-By default `Tags/InvalidTypes` accepts all built-in Ruby classes, constants, and a set of YARD pseudo-types (`nil`, `true`, `false`, `self`, `void`, `undefined`, `unspecified`, `unknown`). If your project uses additional type names that are not real Ruby classes - project-specific aliases, LSP extensions, or informal conventions - you can declare them via `ExtraTypes` so yard-lint does not report them as `InvalidTagType` offenses.
+By default `Tags/InvalidTypes` accepts all built-in Ruby classes, constants, and a set of YARD pseudo-types (`nil`, `true`, `false`, `self`, `void`, `Boolean`, `undefined`, `unspecified`, `unknown`). If your project uses additional type names that are not real Ruby classes - project-specific aliases, LSP extensions, or informal conventions - you can declare them via `ExtraTypes` so yard-lint does not report them as `InvalidTagType` offenses.
 
 ### Project-Specific Type Aliases
 
@@ -400,12 +442,13 @@ Tags/InvalidTypes:
 
 ### Built-In Pseudo-Types (no configuration needed)
 
-The following lowercase YARD pseudo-types are accepted out of the box and do **not** need to be listed in `ExtraTypes`:
+The following YARD pseudo-types are accepted out of the box and do **not** need to be listed in `ExtraTypes`:
 
 | Type | Meaning |
 |------|---------|
 | `nil` | Explicitly nil |
 | `true` / `false` | Boolean literals |
+| `Boolean` | YARD boolean pseudo-type (`true` or `false`) |
 | `self` | Returns the receiver |
 | `void` | No meaningful return value |
 | `undefined` | Type is intentionally unspecified (used by Solargraph) |
@@ -526,7 +569,7 @@ The text formatter also shows the validator path (e.g., `[Documentation/Orphaned
 - **[Wiki Home](https://github.com/mensfeld/yard-lint/wiki)** - Full documentation
 - **[Installation](https://github.com/mensfeld/yard-lint/wiki/Installation)** - Installation guide
 - **[Configuration](https://github.com/mensfeld/yard-lint/wiki/Configuration)** - Complete configuration reference
-- **[Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)** - All 34 validators documented
+- **[Validators](https://github.com/mensfeld/yard-lint/wiki/Validators)** - All 35 validators documented
 - **[Features](https://github.com/mensfeld/yard-lint/wiki/Features)** - All features explained
 
 ### Workflows

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

@@ -114,6 +114,21 @@ Documentation/LineLength:
   Severity: convention
   MaxLength: 120
 
+Documentation/UnderfilledLines:
+  Description: 'Detects documentation prose that wraps before using the available line width.'
+  Enabled: false  # Opt-in validator (the inverse of LineLength)
+  Severity: convention
+  MaxLength: 120
+  # Only flag when the widest non-final line wastes at least this many columns.
+  MinTrailingSpace: 20
+  # Single-line descriptions are never flagged.
+  MinParagraphLines: 2
+  # A non-final line ending in one of these is a deliberate break (skipped).
+  # Add ',' to also respect comma breaks (suppresses more, catches less).
+  SentenceEndChars: ['.', '?', '!', ':', ';']
+  # Skip paragraphs with non-ASCII text (String#length is not display width).
+  SkipNonAscii: true
+
 Documentation/TextSubstitution:
   Description: 'Detects forbidden characters or strings in documentation and suggests replacements.'
   Enabled: false  # Opt-in validator

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

@@ -117,6 +117,16 @@ Documentation/LineLength:
   Severity: error
   MaxLength: 120
 
+Documentation/UnderfilledLines:
+  Description: 'Detects documentation prose that wraps before using the available line width.'
+  Enabled: false  # Opt-in validator (heuristic; stays convention even in strict)
+  Severity: convention
+  MaxLength: 120
+  MinTrailingSpace: 20
+  MinParagraphLines: 2
+  SentenceEndChars: ['.', '?', '!', ':', ';']
+  SkipNonAscii: true
+
 Documentation/TextSubstitution:
   Description: 'Detects forbidden characters or strings in documentation and suggests replacements.'
   Enabled: true

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

@@ -122,6 +122,17 @@ module Yard
           start_line + line_offset
         end
 
+        # Returns the lines of a source file, reading from disk only on the first
+        # call for each unique path. Invalid bytes are scrubbed so that callers
+        # matching regexes against the lines never raise Encoding::CompatibilityError
+        # on a non-UTF-8 source file.
+        # @param file [String] absolute path to the source file
+        # @return [Array<String>] lines of the file, memoized per path
+        def cached_lines(file)
+          @file_cache ||= {}
+          @file_cache[file] ||= File.readlines(file).map!(&:scrub)
+        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

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

@@ -41,17 +41,6 @@ module Yard
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
               collector.puts "#{max_length}|#{violations.join('|')}"
             end
-
-            private
-
-            # Returns the lines of a source file, reading from disk only on the first call
-            # for each unique path.
-            # @param file [String] absolute path to the source file
-            # @return [Array<String>] lines of the file, memoized per path
-            def cached_lines(file)
-              @file_cache ||= {}
-              @file_cache[file] ||= File.readlines(file)
-            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/underfilled_lines/config.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Configuration for UnderfilledLines validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :underfilled_lines
+            self.defaults = {
+              'Enabled' => false,
+              'Severity' => 'convention',
+              # Target width. Re-wrapping prose at this width must save a line for an
+              # offense to be reported. Mirror your Documentation/LineLength MaxLength.
+              'MaxLength' => 120,
+              # Only flag when the widest non-final line of the paragraph leaves at
+              # least this many unused columns - avoids nitpicking near-full prose.
+              'MinTrailingSpace' => 20,
+              # Paragraphs shorter than this are never flagged (a single line cannot
+              # be "under-filled" - there is nothing to pull up onto it).
+              'MinParagraphLines' => 2,
+              # A non-final prose line ending in one of these characters is treated as
+              # a deliberate sentence/clause break, and its paragraph is left alone.
+              # Add ',' to also respect comma breaks (suppresses more, catches less).
+              'SentenceEndChars' => ['.', '?', '!', ':', ';'],
+              # Skip paragraphs containing non-ASCII text: String#length is not a
+              # reliable display width for CJK/full-width/emoji content.
+              'SkipNonAscii' => true
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines/messages_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Builds human-readable messages for UnderfilledLines violations.
+          class MessagesBuilder
+            class << self
+              # @param offense [Hash] offense details with :actual_lines, :reflowed_lines,
+              #   :widest_fill, :max_length and :object_name
+              # @return [String] formatted message
+              def call(offense)
+                actual = offense[:actual_lines]
+                reflowed = offense[:reflowed_lines]
+                widest = offense[:widest_fill]
+                max_length = offense[:max_length]
+                object_name = offense[:object_name]
+
+                "Documentation paragraph uses #{actual} lines but fits in #{reflowed} " \
+                  "at <=#{max_length} cols [widest line filled to #{widest}/#{max_length}] " \
+                  "for '#{object_name}'"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines/parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Parses UnderfilledLines validator output into structured violation hashes.
+          #
+          # Expected format (two lines per object with violations):
+          #   file.rb:OBJECT_LINE: ObjectName
+          #   MAX_LENGTH|START:ACTUAL:REFLOW:WIDEST|START:ACTUAL:REFLOW:WIDEST|...
+          class Parser < Parsers::Base
+            # @param output [String] raw validator output
+            # @return [Array<Hash>] array of violation hashes
+            def call(output, **)
+              return [] if output.nil? || output.empty?
+
+              violations = []
+              lines = output.lines.map(&:chomp)
+
+              i = 0
+              while i < lines.size
+                location_match = lines[i].match(/^(.+):(\d+): (.+)$/)
+
+                if location_match
+                  file_path = location_match[1]
+                  object_line = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  i += 1
+                  if i < lines.size
+                    parts = lines[i].split('|')
+                    max_length = parts.shift.to_i
+
+                    parts.each do |part|
+                      start, actual, reflow, widest = part.split(':', 4)
+                      next unless start && actual && reflow && widest
+
+                      violations << {
+                        location: file_path,
+                        line: start.to_i,
+                        object_line: object_line,
+                        object_name: object_name,
+                        actual_lines: actual.to_i,
+                        reflowed_lines: reflow.to_i,
+                        widest_fill: widest.to_i,
+                        max_length: max_length
+                      }
+                    end
+                  end
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines/result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Result wrapper for UnderfilledLines validator.
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'line'
+            self.offense_name = 'UnderfilledLines'
+
+            private
+
+            # @param offense [Hash] offense details from the parser
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Detects documentation prose that wraps before using the available line width.
+          #
+          # Uses YARD's `docstring.line_range` to locate the exact source lines belonging
+          # to the docstring block (mirroring {LineLength}), classifies each line as prose
+          # or structural, groups contiguous prose into paragraphs, and reports a
+          # paragraph when greedily re-wrapping it at `MaxLength` would use fewer lines.
+          class Validator < Validators::Base
+            in_process visibility: :all
+
+            # Characters that may trail a sentence boundary char without changing the
+            # fact that the line ends a clause (closing bracket/quote/backtick).
+            TRAILING_CLOSERS = /[)\]"'`]+\z/
+
+            # Execute query for a single object during in-process execution.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              return unless object.file && File.exist?(object.file)
+              return if object.docstring.all.empty?
+
+              line_range = object.docstring.line_range
+              return unless line_range
+              return if duplicate_docstring?(object)
+
+              max_length = config_or_default('MaxLength').to_i
+              min_trailing = config_or_default('MinTrailingSpace').to_i
+              min_lines = [config_or_default('MinParagraphLines').to_i, 2].max
+              boundary = Array(config_or_default('SentenceEndChars'))
+              skip_non_ascii = config_or_default('SkipNonAscii')
+
+              source_lines = cached_lines(object.file)
+              classified = classify_lines(line_range, source_lines, skip_non_ascii)
+
+              violations = []
+              group_paragraphs(classified).each do |paragraph|
+                next if paragraph.size < min_lines
+                next if ventilated?(paragraph, boundary)
+
+                actual = paragraph.size
+                reflowed = reflow_count(paragraph, max_length)
+                next unless reflowed < actual
+
+                widest = paragraph[0..-2].map { |line| line[:length] }.max
+                next if (max_length - widest) < min_trailing
+
+                violations << "#{paragraph.first[:line_no]}:#{actual}:#{reflowed}:#{widest}"
+              end
+
+              return if violations.empty?
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts "#{max_length}|#{violations.join('|')}"
+            end
+
+            private
+
+            # Classify each source line in the docstring range. Plain-prose lines become
+            # hashes; everything else (blank lines, tags, code, markdown structure) is a
+            # `:break` marker that separates paragraphs.
+            # @param line_range [Range] absolute source line numbers of the docstring
+            # @param source_lines [Array<String>] raw lines of the source file
+            # @param skip_non_ascii [Boolean] treat non-ASCII lines as structural
+            # @return [Array<Hash, Symbol>] prose hashes interleaved with :break markers
+            def classify_lines(line_range, source_lines, skip_non_ascii)
+              base_indent = base_indent_for(line_range, source_lines)
+              result = []
+              in_fence = false
+              in_tag_region = false
+
+              line_range.each do |line_no|
+                raw = source_lines[line_no - 1].to_s.rstrip
+                marker = raw.match(/\A(\s*#+\s?)(.*)\z/)
+
+                # Not a comment line (e.g. the definition itself, or a block comment body)
+                unless marker
+                  result << :break
+                  in_tag_region = false
+                  next
+                end
+
+                content = marker[2]
+                stripped = content.strip
+
+                # Fenced code block delimiters toggle the fence; the delimiter line and
+                # everything inside it is structural.
+                if stripped.start_with?('```', '~~~')
+                  in_fence = !in_fence
+                  result << :break
+                  next
+                end
+                if in_fence
+                  result << :break
+                  next
+                end
+
+                if stripped.empty?
+                  result << :break
+                  in_tag_region = false
+                  next
+                end
+
+                # A real YARD tag/directive begins at column 0 of the comment content.
+                # It and its indented continuation lines are skipped; only the free-text
+                # description body is checked.
+                if content.start_with?('@')
+                  in_tag_region = true
+                  result << :break
+                  next
+                end
+                if in_tag_region
+                  if content.match?(/\A[ \t]/)
+                    result << :break
+                    next
+                  end
+                  in_tag_region = false
+                end
+
+                # Lines indented past the block's base indentation are code samples,
+                # ASCII diagrams or nested list continuations - not flowing prose.
+                indent = content.length - content.lstrip.length
+                if indent > base_indent || structural_content?(stripped, skip_non_ascii)
+                  result << :break
+                  next
+                end
+
+                result << {
+                  line_no: line_no,
+                  prefix_width: raw.length - stripped.length,
+                  content: stripped,
+                  length: raw.length
+                }
+              end
+
+              result
+            end
+
+            # The smallest content indentation among non-empty comment lines in the
+            # range. Flowing prose sits at this base; anything deeper is treated as a
+            # nested, code or diagram line.
+            # @param line_range [Range] absolute source line numbers of the docstring
+            # @param source_lines [Array<String>] raw lines of the source file
+            # @return [Integer] base indentation in columns (0 for normal `# ` comments)
+            def base_indent_for(line_range, source_lines)
+              indents = []
+              line_range.each do |line_no|
+                raw = source_lines[line_no - 1].to_s.rstrip
+                marker = raw.match(/\A(\s*#+\s?)(.*)\z/)
+                next unless marker
+
+                content = marker[2]
+                next if content.strip.empty?
+
+                indents << (content.length - content.lstrip.length)
+              end
+              indents.min || 0
+            end
+
+            # Whether a prose-looking comment line is actually structural and must not
+            # take part in reflow (markdown, code, diagrams, RDoc directives, ...).
+            # @param stripped [String] comment content, stripped of the marker and whitespace
+            # @param skip_non_ascii [Boolean] treat non-ASCII content as structural
+            # @return [Boolean]
+            def structural_content?(stripped, skip_non_ascii)
+              return true if skip_non_ascii && !stripped.ascii_only?
+              # Markdown heading, blockquote
+              return true if stripped.start_with?('#', '>')
+              # Table row
+              return true if stripped.include?('|')
+              # List items (bulleted or ordered)
+              return true if stripped.match?(/\A[-*+]\s/)
+              return true if stripped.match?(/\A\d+[.)]\s/)
+              # Thematic break (---, ***, ___)
+              return true if stripped.match?(/\A([-*_])\1\1+\z/)
+              # RDoc directives
+              return true if stripped.match?(/\A:\w+:/)
+              return true if stripped.end_with?(':nodoc:', ':doc:')
+              # Intentional hard break / hyphenation
+              return true if stripped.end_with?('-')
+              # Column alignment (2+ internal spaces) or box-drawing diagrams
+              return true if stripped.match?(/\S {2,}\S/)
+              return true if stripped.match?(/[─-╿▀-▟]/)
+
+              false
+            end
+
+            # Group the classified entries into paragraphs: maximal runs of contiguous
+            # prose lines sharing the same comment-marker indentation.
+            # @param classified [Array<Hash, Symbol>] output of {#classify_lines}
+            # @return [Array<Array<Hash>>] paragraphs, each an array of prose line hashes
+            def group_paragraphs(classified)
+              paragraphs = []
+              current = []
+
+              flush = lambda do
+                paragraphs << current unless current.empty?
+                current = []
+              end
+
+              classified.each do |entry|
+                if entry == :break
+                  flush.call
+                elsif current.empty? || current.last[:prefix_width] == entry[:prefix_width]
+                  current << entry
+                else
+                  flush.call
+                  current << entry
+                end
+              end
+              flush.call
+
+              paragraphs
+            end
+
+            # Whether a paragraph is deliberately broken one sentence/clause per line.
+            # True when every non-final line ends at a sentence boundary character.
+            # @param paragraph [Array<Hash>] prose line hashes
+            # @param boundary [Array<String>] sentence-ending characters
+            # @return [Boolean]
+            def ventilated?(paragraph, boundary)
+              return false if boundary.empty?
+
+              paragraph[0..-2].all? do |line|
+                last = line[:content].sub(TRAILING_CLOSERS, '')[-1]
+                last && boundary.include?(last)
+              end
+            end
+
+            # Number of lines the paragraph's words occupy when greedily wrapped at
+            # `max_length`, using the paragraph's comment-marker prefix on every line.
+            # A word that does not fit starts a new line, so breaks forced by an
+            # unbreakable long token (URL, namespaced constant) are reproduced and do
+            # not count as savings.
+            # @param paragraph [Array<Hash>] prose line hashes
+            # @param max_length [Integer] target width
+            # @return [Integer] number of wrapped lines
+            def reflow_count(paragraph, max_length)
+              prefix_width = paragraph.first[:prefix_width]
+              words = paragraph.flat_map { |line| line[:content].split }
+              return paragraph.size if words.empty?
+
+              lines = 1
+              current = prefix_width + words.first.length
+              words.drop(1).each do |word|
+                if current + 1 + word.length <= max_length
+                  current += 1 + word.length
+                else
+                  lines += 1
+                  current = prefix_width + word.length
+                end
+              end
+              lines
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # UnderfilledLines validator
+        #
+        # The inverse of {LineLength}: instead of flagging documentation lines that are
+        # too *long*, it flags documentation prose paragraphs that wrap **too early** -
+        # text that uses only a fraction of the available width and spills onto extra
+        # lines, wasting vertical space. This pattern is common in AI-generated docs.
+        #
+        # Only the free-text description body is checked. YARD tags (`@param`, `@return`,
+        # `@example`, ...), fenced and indented code, lists, tables, headings,
+        # blockquotes and non-ASCII text are left untouched. A paragraph is reported
+        # only when *all* of these hold, so ambiguous cases are never flagged:
+        #
+        # * greedily re-wrapping its words at `MaxLength` would genuinely use fewer lines;
+        # * the unused space on its widest line is at least `MinTrailingSpace` columns;
+        # * it is not deliberately broken one sentence/clause per line (every non-final
+        #   line ending at a `SentenceEndChars` boundary is treated as an intentional
+        #   semantic line break and skipped).
+        #
+        # Disabled by default - this is a stylistic, opinionated check. Enable it to
+        # tighten draft or AI-written documentation.
+        #
+        # @example Bad - prose wraps at ~55 columns when 120 are available
+        #   # Processes the incoming payload and returns a normalized
+        #   # hash that downstream consumers can rely on for routing.
+        #   def process(payload)
+        #   end
+        #
+        # @example Good - prose fills the available width before wrapping
+        #   # Processes the incoming payload and returns a normalized hash that downstream
+        #   # consumers can rely on for routing.
+        #   def process(payload)
+        #   end
+        #
+        # @example Good - semantic line breaks (one sentence per line) are never flagged
+        #   # Validates the input.
+        #   # Normalizes the casing.
+        #   # Persists the record.
+        #   def call
+        #   end
+        #
+        # ## Configuration
+        #
+        # To enable with custom settings:
+        #
+        #     Documentation/UnderfilledLines:
+        #       Enabled: true
+        #       MaxLength: 120
+        #       MinTrailingSpace: 20
+        #
+        # ## Reliability
+        #
+        # Unlike {LineLength} - which measures an objective property (characters over a
+        # limit) - "this line should have been longer" is a stylistic judgement. The
+        # validator is deliberately conservative and biased toward silence: it would
+        # rather miss a case than emit a false positive. Projects that use semantic line
+        # breaks (one sentence or clause per line, see https://sembr.org) should leave it
+        # off, or add `,` to `SentenceEndChars`.
+        #
+        # To disable:
+        #
+        #     Documentation/UnderfilledLines:
+        #       Enabled: false
+        module UnderfilledLines
+        end
+      end
+    end
+  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.7.0'
+    VERSION = '1.8.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -121,6 +121,12 @@ files:
 - lib/yard/lint/validators/documentation/text_substitution/parser.rb
 - lib/yard/lint/validators/documentation/text_substitution/result.rb
 - lib/yard/lint/validators/documentation/text_substitution/validator.rb
+- lib/yard/lint/validators/documentation/underfilled_lines.rb
+- lib/yard/lint/validators/documentation/underfilled_lines/config.rb
+- lib/yard/lint/validators/documentation/underfilled_lines/messages_builder.rb
+- lib/yard/lint/validators/documentation/underfilled_lines/parser.rb
+- lib/yard/lint/validators/documentation/underfilled_lines/result.rb
+- lib/yard/lint/validators/documentation/underfilled_lines/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