yard-lint 1.10.0 → 1.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37286ca0e1a4253fd44af81beda164e713f58903e9d7c06ccf7dc06484c76be9
-  data.tar.gz: 2b5b3dc5eaed758b12b07a5a2a67ad537dbf56e8459a5075e796850a73deb2a2
+  metadata.gz: e1b9f3a39ce5fb15c2a1ace664e45d393fb70e429220085ebd4a7881aa2496cc
+  data.tar.gz: 207fb47ddd283bd62755c6f5736652166caed19a342f601ce78cfe73c0aad5e9
 SHA512:
-  metadata.gz: ca788e4ee2a91c5990b20c953bf28bfeaa731c6feaa4183a3bb323e04f5a198af40a7f30d60e4a714d9361a0ab589a9c202f766202e7c6468ad7c7407b55d5ea
-  data.tar.gz: a38ddad77479fdcc11f18d530fafacd090d079827a1e93ad423f2dc839e5e50cc072ab04a7a2150836f4f654f560e098abf6e59c5b38d970f6d93d39a373b8cf
+  metadata.gz: 7898934b15acdea1b39a244e6224969cef3848427b02db1711c87480ff8459b481920eb6a378fe25296bf0c2dc708d7f3b63ec7c8bd25effb7ea92d8c21179df
+  data.tar.gz: cb7525e59baebfe5cbb1e192ed91d38c6c75d04a4fd1ed9c60db1616794e66b67b46b39cefd5fa734565b30bb7bb4419fe672cbe798b2019443c0d5f59e7f7ae

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.10.2 (2026-07-24)
+- **[Bugfix]** `Semantic/AbstractMethods` no longer flags an `@abstract` method whose body is `fail NotImplementedError`. `fail` is a built-in alias of `raise` (`Kernel#fail`), so `fail NotImplementedError` is an identical abstract-method guard to `raise NotImplementedError`, but the `AllowedImplementations` patterns are written with `raise` and were matched literally. A leading `fail` keyword is now normalized to `raise` before matching, so both forms are recognized (and any custom `raise`-based `AllowedImplementations` pattern automatically covers its `fail` alias). Identifiers such as `failure` and non-leading `fail(...)` calls are left untouched.
+
+## 1.10.1 (2026-07-24)
+- **[Bugfix]** `Documentation/BlankLineBeforeDefinition` no longer reports a foreign comment block above a definition as documentation that was accidentally detached from it. When the object is documented (non-empty docstring) but that docstring did not come from the comment block sitting above this definition, the block is not a detached docstring - it is a file-level license/copyright banner, an encoding note, or an unrelated comment above a namespace reopening whose documentation lives in another file. The check compares the object's docstring against the block's text, so it recognizes any such banner without hardcoding its wording. Definitions whose documentation was genuinely lost (an undocumented object with a comment block detached above it) are still reported.
+
 ## 1.10.0 (2026-07-24)
 - **[Feature]** Added `Documentation/DuplicateNamespaceComment` (enabled by default, severity `warning`) - detects namespaces (modules and classes) that carry a YARD documentation comment in more than one file. When a namespace is reopened across files and documented in several of them, YARD merges the reopenings into a single object and keeps only one docstring, silently discarding the rest (the last documented reopening wins, with no warning), so competing descriptions are lost. This is a common accident for shared namespaces (e.g. `Users` or `Users::Operations`) spread across many files; it does not affect a leaf object such as `Users::Operations::Create` that lives in a single file. Because YARD does not record which reopening carried a comment, the validator re-reads each definition site to detect the documented ones (ignoring blank-line-detached comments and directive/magic comments), and reports one offense per namespace documented in two or more files, listing every documented location and noting when the docstrings differ (meaning content is actually lost). Configurable via the standard `Enabled` and `Severity` keys.
 

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

@@ -21,9 +21,19 @@ module Yard
               source_lines = File.readlines(object.file)
               definition_line = object.line - 1
 
-              blank_count, has_doc_block = analyze_spacing(source_lines, definition_line)
+              blank_count, doc_block_line = analyze_spacing(source_lines, definition_line)
 
-              return if blank_count.zero? || !has_doc_block
+              return if blank_count.zero? || doc_block_line.nil?
+
+              # Only a comment block that is genuinely THIS object's documentation can have
+              # been detached from it by the blank line. When the object is documented (its
+              # docstring is non-empty) but that docstring did not come from the comment block
+              # sitting above this definition, the block is a foreign comment - a file-level
+              # license/copyright banner, an encoding note, or an unrelated comment above a
+              # namespace reopening that is documented in another file - and the blank line is
+              # intentional. This is decided by comparing the object's docstring against the
+              # block's text, so it covers any such banner without hardcoding its wording.
+              return if foreign_comment_block?(object, source_lines, doc_block_line)
 
               violation_type = blank_count >= 2 ? 'orphaned' : 'single'
 
@@ -38,10 +48,10 @@ module Yard
             # Analyze spacing between documentation and definition
             # @param source_lines [Array<String>] lines of source file
             # @param definition_line [Integer] 0-indexed line of definition
-            # @return [Array<Integer, Boolean>] blank count and whether doc block exists
+            # @return [Array<Integer, Integer, nil>] blank count and the 0-indexed line of the
+            #   nearest documentation comment above the definition (nil when there is none)
             def analyze_spacing(source_lines, definition_line)
               blank_count = 0
-              has_doc_block = false
 
               (definition_line - 1).downto(0) do |i|
                 line = source_lines[i].to_s.rstrip
@@ -56,15 +66,65 @@ module Yard
                   # spurious blank-line offenses for undocumented definitions.
                   next if non_documentation_comment?(stripped)
 
-                  has_doc_block = true
-                  break
+                  return [blank_count, i]
                 else
                   # Non-comment, non-blank line - no documentation above
                   break
                 end
               end
 
-              [blank_count, has_doc_block]
+              [blank_count, nil]
+            end
+
+            # Whether the comment block above the definition is NOT the source of the object's
+            # documentation - a file banner or an unrelated comment rather than a docstring
+            # this definition lost to the blank line.
+            #
+            # An object with no docstring at all has genuinely orphaned documentation, so the
+            # block above is still reported. When the object IS documented, the block only
+            # counts as detached documentation if the docstring's text actually came from it;
+            # a license header or a comment above a reopening documented elsewhere carries
+            # different text and is left alone.
+            # @param object [YARD::CodeObjects::Base] the code object being checked
+            # @param source_lines [Array<String>] lines of source file
+            # @param doc_line [Integer] 0-indexed line of the nearest comment above the definition
+            # @return [Boolean]
+            def foreign_comment_block?(object, source_lines, doc_line)
+              docstring = object.docstring.to_s.strip
+              return false if docstring.empty?
+
+              block = comment_block_text(source_lines, doc_line)
+              first_line = normalize(docstring.lines.first.to_s)
+              return false if first_line.empty?
+
+              !normalize(block).include?(first_line)
+            end
+
+            # Text of the contiguous comment block that contains `doc_line`, stripped of the
+            # comment markers and joined into a single string.
+            # @param source_lines [Array<String>] lines of source file
+            # @param doc_line [Integer] 0-indexed line within the comment block
+            # @return [String]
+            def comment_block_text(source_lines, doc_line)
+              first = doc_line
+              first -= 1 while first.positive? && comment_line?(source_lines[first - 1])
+              last = doc_line
+              last += 1 while last + 1 < source_lines.length && comment_line?(source_lines[last + 1])
+
+              source_lines[first..last].map { |line| line.sub(/\A\s*#+\s?/, '').strip }.join(' ')
+            end
+
+            # @param line [String, nil] a source line
+            # @return [Boolean] whether the line is a comment line
+            def comment_line?(line)
+              line.to_s.strip.start_with?('#')
+            end
+
+            # Collapse whitespace so wrapped docstrings and their source comments compare equal.
+            # @param text [String]
+            # @return [String]
+            def normalize(text)
+              text.strip.gsub(/\s+/, ' ')
             end
 
             # Check if a comment line is a Ruby magic comment

data/lib/yard/lint/validators/semantic/abstract_methods/validator.rb

@@ -46,7 +46,7 @@ module Yard
               has_real_implementation = body_lines.any? do |line|
                 next false if line.start_with?('#') || line == 'end'
 
-                allowed.none? { |pattern| line.match?(pattern) }
+                allowed.none? { |pattern| normalize_raise_alias(line).match?(pattern) }
               end
 
               return unless has_real_implementation
@@ -69,6 +69,18 @@ module Yard
               end
             end
 
+            # Rewrites a leading `fail` keyword to `raise` so the two are treated alike when
+            # matching AllowedImplementations. `fail` is a built-in alias of `raise`
+            # (`Kernel#fail`), so `fail NotImplementedError` is an identical abstract-method
+            # guard to `raise NotImplementedError`, but the configured patterns are written
+            # with `raise`. Only a leading keyword is rewritten, so identifiers such as
+            # `failure` or a `fail(...)` call elsewhere in a line are left untouched.
+            # @param line [String] a stripped body line
+            # @return [String]
+            def normalize_raise_alias(line)
+              line.sub(/\Afail\b/, 'raise')
+            end
+
             # Joins lines that are continuations of the previous statement (the
             # previous line ends with a comma or a backslash) into a single
             # logical line.

data/lib/yard/lint/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.10.2
 platform: ruby
 authors:
 - Maciej Mensfeld