yard-lint 1.3.0.rc1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb5e9ce0ee619596a8e5d35f7d46a9494ac6e0682215ad0f0bf48a3a87ee8f04
-  data.tar.gz: 5eff9bd848c484de1c752d60577f9d3ce2910a8d4f61825b02d1552a9209c598
+  metadata.gz: 776d4e0a37ddbafe6b61e0df58c8a663432a04397c0d6cd9b36527484cde5675
+  data.tar.gz: afe2b858507d15d1b264cd8ac1a15dd0285eac638ea227643f23fb41977e6521
 SHA512:
-  metadata.gz: 1e435ab938578b0c84ce189def96cfe2c0ab3e0d5881ab3a7d8e1c89b4e082fa21b0388175685ccce08df1a95bcacca8d5c61a703f0aaf81f9950b6bd95119a8
-  data.tar.gz: 1de8b9658868b6bda3504151486ffa25fc86ee379d3fd41e19b05b5bf93024bd6f244bfaf79e97d45b08e4a3862db890dda9a4f8d8d9576e616021c945a43bf9
+  metadata.gz: d2076e759985b33a992394ebba9fc769aa70b3a16fc7914db8e4fb16bb3aac2d1d8bb5b9e6532d65bb545767321d59e1cf2c1ece89588bef12898cf2238dd05d
+  data.tar.gz: '08c2a18358bc5ee1fef76cd5f5d627c9859b99e1ebd7789b29babc1d1317c295e8d688583e7a456d744ff87677e9ac2f3abb925a1f8f176e1bff96a0622c00a9'

data/.ruby-version

@@ -0,0 +1 @@
+4.0

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # YARD-Lint Changelog
 
-## 1.3.0 (Unreleased)
+## 1.4.0 (2026-01-19)
+- **[Fix]** Handle directive definitions depending on file load order (#65, @zaben903)
+- **[CI]** Update Ruby 4.0 from preview2 to stable release as the default version
+  - Ruby 4.0 is now the default for yard-lint dogfooding and gem release workflows
+  - Code coverage is now tracked only on Ruby 4.0
+  - Added `.ruby-version` file specifying Ruby 4.0
+  - Continues to support Ruby 3.2, 3.3, and 3.4
+- **[Feature]** Add `Tags/ForbiddenTags` validator to detect forbidden tag and type combinations (#59)
+  - Allows projects to disallow specific tag patterns like `@return [void]`
+  - Supports tag-only patterns (forbid entire tag) and tag+type patterns
+  - Configurable `ForbiddenPatterns` list with `Tag` and optional `Types` keys
+  - Use case: Enforce documentation of side effects instead of `@return [void]`
+  - Use case: Forbid overly generic types like `@param [Object]`
+  - Use case: Forbid specific tags entirely (e.g., `@api`)
+  - Disabled by default (opt-in validator) with 'convention' severity
+
+## 1.3.0 (2025-12-10)
 - **[Fix]** Expand `Tags/Order` default `EnforcedOrder` to include all standard YARD tags
   - Previous config only included: `param`, `option`, `return`, `raise`, `example`
   - Now includes full order: `param`, `option`, `yield`, `yieldparam`, `yieldreturn`, `return`, `raise`, `see`, `example`, `note`, `todo`

data/README.md

@@ -38,6 +38,7 @@ YARD-Lint validates your YARD documentation for:
 - **Blank lines before definitions**: Detects blank lines between YARD documentation and method/class/module definitions (single blank line = convention violation, 2+ blank lines = orphaned documentation that YARD ignores)
 - **Informal notation patterns**: Detects `Note:`, `TODO:`, `See:` etc. and suggests proper YARD tags (`@note`, `@todo`, `@see`)
 - **Tag group separation**: Enforces blank lines between different YARD tag groups (e.g., between `@param` and `@return` tags) for improved readability
+- **Forbidden tag patterns**: Configurable patterns to disallow specific tags or tag/type combinations (e.g., `@return [void]`, `@param [Object]`)
 - **YARD warnings**: Unknown tags, invalid directives, duplicated parameter names, and more
 - **Smart suggestions**: Provides "did you mean" suggestions for typos in parameter names using Ruby's `did_you_mean` gem with Levenshtein distance fallback
 
@@ -555,6 +556,7 @@ Supported glob patterns:
 | `Tags/RedundantParamDescription` | Detects meaningless parameter descriptions that add no value beyond the parameter name | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `CheckedTags`, `Articles`, `MaxRedundantWords`, `MinMeaningfulLength`, `GenericTerms`, `EnabledPatterns` |
 | `Tags/InformalNotation` | Detects informal notation patterns (`Note:`, `TODO:`, etc.) and suggests proper YARD tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `CaseSensitive`, `RequireStartOfLine`, `Patterns` |
 | `Tags/TagGroupSeparator` | Enforces blank line separators between different YARD tag groups (e.g., between `@param` and `@return` tags) | Disabled (opt-in) | `Enabled`, `Severity`, `Exclude`, `TagGroups`, `RequireAfterDescription` |
+| `Tags/ForbiddenTags` | Detects forbidden tag and type combinations (e.g., `@return [void]`, `@param [Object]`) | Disabled (opt-in) | `Enabled`, `Severity`, `Exclude`, `ForbiddenPatterns` |
 | **Warnings Validators** |
 | `Warnings/UnknownTag` | Detects unknown YARD tags with "did you mean" suggestions | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
 | `Warnings/UnknownDirective` | Detects unknown YARD directives | Enabled (error) | `Enabled`, `Severity`, `Exclude` |

data/lib/yard/lint/executor/in_process_registry.rb

@@ -33,6 +33,15 @@ module Yard
             original_level = YARD::Logger.instance.level
             YARD::Logger.instance.level = 4 # Only show fatal errors
 
+            # First pass: parse all files to process directive definitions
+            YARD.parse(files)
+
+            # Clear checksums to force reparsing without clearing the registry.
+            # This allows macro definitions from the first pass to be available
+            # during the second pass, enabling proper directive expansion regardless of parse order.
+            YARD::Registry.checksums.clear
+
+            # Second pass: reparse files now that all directive definitions are available
             @warnings = capture_warnings { YARD.parse(files) }
             @parsed = true
 

data/lib/yard/lint/ext/irb_notifier_shim.rb

@@ -1,16 +1,29 @@
 # frozen_string_literal: true
 
-# Shim for IRB::Notifier to avoid IRB dependency in Ruby 3.5+
+# Shim for IRB::Notifier to avoid IRB dependency in Ruby 3.5+/4.0+
 #
-# YARD's legacy parser vendors old IRB code that depends on IRB::Notifier.
+# WHY THIS SHIM IS NEEDED:
 # In Ruby 3.5+, IRB is no longer part of the default gems and must be explicitly installed.
-# This shim provides just enough functionality to keep YARD's legacy parser working
-# without requiring the full IRB gem as a dependency.
+# YARD's codebase has a dependency chain that triggers `require "irb/notifier"` even when
+# using the modern Ripper-based parser:
 #
-# The notifier is only used for debug output in YARD's legacy parser, which we don't need.
+#   @!attribute directive parsing
+#     → YARD::Tags::OverloadTag#parse_signature
+#       → YARD::Parser::Ruby::Legacy::TokenList
+#         → ruby_lex.rb
+#           → irb/slex.rb
+#             → require "irb/notifier"  ← FAILS without IRB gem or this shim
+#
+# This happens because YARD uses its legacy TokenList for parsing attribute signatures,
+# regardless of which main parser is selected. Until YARD removes this dependency,
+# this shim is required for Ruby 3.5+/4.0+ compatibility.
+#
+# WHAT THIS SHIM DOES:
+# Provides a minimal no-op implementation of IRB::Notifier that satisfies YARD's
+# requirements. The notifier is only used for debug output which we don't need.
 #
 # IMPORTANT: This shim only loads if IRB::Notifier is not already defined.
-# If IRB gem is present, we use the real implementation instead.
+# If the IRB gem is present, we use the real implementation instead.
 
 # Only load the shim if IRB::Notifier is not already defined
 unless defined?(IRB::Notifier)

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

@@ -241,6 +241,20 @@ Tags/TagGroupSeparator:
     yield: [yield, yieldparam, yieldreturn]
   RequireAfterDescription: false
 
+Tags/ForbiddenTags:
+  Description: 'Detects forbidden tag and type combinations.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  ForbiddenPatterns: []
+  # Example patterns:
+  # - Tag: return
+  #   Types:
+  #     - void
+  # - Tag: param
+  #   Types:
+  #     - Object
+  # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
+
 # Warnings validators - catches YARD parser errors
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'

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

@@ -245,6 +245,20 @@ Tags/TagGroupSeparator:
     yield: [yield, yieldparam, yieldreturn]
   RequireAfterDescription: false
 
+Tags/ForbiddenTags:
+  Description: 'Detects forbidden tag and type combinations.'
+  Enabled: false  # Opt-in validator
+  Severity: error
+  ForbiddenPatterns: []
+  # Example patterns:
+  # - Tag: return
+  #   Types:
+  #     - void
+  # - Tag: param
+  #   Types:
+  #     - Object
+  # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
+
 # Warnings validators - catches YARD parser errors
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'

data/lib/yard/lint/validators/tags/forbidden_tags/config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ForbiddenTags
+          # Configuration for ForbiddenTags validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :forbidden_tags
+            self.defaults = {
+              'Enabled' => false,
+              'Severity' => 'convention',
+              'ForbiddenPatterns' => []
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/forbidden_tags/messages_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ForbiddenTags
+          # Builds human-readable messages for ForbiddenTags violations
+          class MessagesBuilder
+            class << self
+              # Formats a forbidden tag violation message
+              # @param offense [Hash] offense details with :tag_name, :types_text, :pattern_types
+              # @return [String] formatted message
+              def call(offense)
+                tag_name = offense[:tag_name]
+                types_text = offense[:types_text]
+                pattern_types = offense[:pattern_types]
+
+                if pattern_types.nil? || pattern_types.empty?
+                  "Forbidden tag detected: @#{tag_name}. " \
+                    'This tag is not allowed by project configuration.'
+                else
+                  type_display = types_text.empty? ? '' : " [#{types_text}]"
+                  "Forbidden tag pattern detected: @#{tag_name}#{type_display}. " \
+                    "Type(s) '#{pattern_types}' are not allowed for @#{tag_name}."
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/forbidden_tags/parser.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ForbiddenTags
+          # Parser for ForbiddenTags validator output
+          # Parses in-process output that reports forbidden tag patterns
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses validator output and extracts forbidden tag violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ObjectName
+            #   tag_name|types_text|pattern_types
+            # @param yard_output [String] raw validator output
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+              violations = []
+
+              lines.each_slice(2) do |location_line, details_line|
+                next unless location_line && details_line
+
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                details = details_line.split('|', 3)
+                next if details.empty?
+
+                tag_name, types_text, pattern_types = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  tag_name: tag_name,
+                  types_text: types_text || '',
+                  pattern_types: pattern_types || ''
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/forbidden_tags/result.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ForbiddenTags
+          # Result wrapper for ForbiddenTags validator
+          # Formats parsed violations into offense objects
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'tag'
+            self.offense_name = 'ForbiddenTags'
+
+            private
+
+            # Builds a human-readable message for the offense
+            # @param offense [Hash] offense details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ForbiddenTags
+          # Validates that forbidden tag/type combinations are not used
+          class Validator < Base
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
+
+            # Execute query for a single object during in-process execution.
+            # Checks for forbidden tag/type combinations in docstrings.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            def in_process_query(object, collector)
+              patterns = forbidden_patterns
+              return if patterns.empty?
+
+              object.docstring.tags.each do |tag|
+                patterns.each do |pattern|
+                  next unless matches_pattern?(tag, pattern)
+
+                  collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                  collector.puts build_details(tag, pattern)
+                end
+              end
+            end
+
+            private
+
+            # @return [Array<Hash>] configured forbidden patterns
+            def forbidden_patterns
+              config_or_default('ForbiddenPatterns')
+            end
+
+            # Check if a tag matches a forbidden pattern
+            # @param tag [YARD::Tags::Tag] the tag to check
+            # @param pattern [Hash] the forbidden pattern with 'Tag' and optional 'Types'
+            # @return [Boolean] true if tag matches the pattern
+            def matches_pattern?(tag, pattern)
+              return false unless tag.tag_name == pattern['Tag']
+
+              pattern_types = pattern['Types']
+              return true if pattern_types.nil? || pattern_types.empty?
+
+              tag_types = tag.types || []
+              (tag_types & pattern_types).any?
+            end
+
+            # Build details string for output
+            # @param tag [YARD::Tags::Tag] the matched tag
+            # @param pattern [Hash] the matched pattern
+            # @return [String] details line for parser
+            def build_details(tag, pattern)
+              types_text = (tag.types || []).join(',')
+              pattern_types = (pattern['Types'] || []).join(',')
+              "#{tag.tag_name}|#{types_text}|#{pattern_types}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # ForbiddenTags validator
+        #
+        # Detects forbidden YARD tag and type combinations. This is useful for
+        # enforcing project-specific documentation conventions, such as:
+        # - Disallowing `@return [void]` (prefer documenting side effects)
+        # - Forbidding overly generic types like `@param [Object]`
+        # - Preventing use of certain tags entirely
+        #
+        # This validator is disabled by default (opt-in).
+        #
+        # ## Configuration
+        #
+        # To enable and configure forbidden patterns:
+        #
+        #     Tags/ForbiddenTags:
+        #       Enabled: true
+        #       Severity: convention
+        #       ForbiddenPatterns:
+        #         # Forbid @return [void]
+        #         - Tag: return
+        #           Types:
+        #             - void
+        #         # Forbid @param [Object]
+        #         - Tag: param
+        #           Types:
+        #             - Object
+        #         # Forbid @api tag entirely
+        #         - Tag: api
+        #
+        # @example Bad - @return [void] (when configured as forbidden)
+        #   # Does something
+        #   # @return [void]
+        #   def do_something
+        #     puts 'done'
+        #   end
+        #
+        # @example Good - Document side effects instead
+        #   # Prints 'done' to stdout
+        #   # @return [nil] always returns nil after printing
+        #   def do_something
+        #     puts 'done'
+        #   end
+        #
+        # @example Bad - @param [Object] (when configured as forbidden)
+        #   # Process data
+        #   # @param data [Object] the data
+        #   def process(data)
+        #     data.to_s
+        #   end
+        #
+        # @example Good - Use specific type
+        #   # Process data
+        #   # @param data [String, Integer] the data to process
+        #   def process(data)
+        #     data.to_s
+        #   end
+        module ForbiddenTags
+        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.3.0.rc1'
+    VERSION = '1.4.0'
   end
 end

data/lib/yard-lint.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Load IRB notifier shim before YARD to avoid IRB dependency in Ruby 3.5+
+# Load IRB notifier shim before YARD to avoid IRB dependency in Ruby 3.5+/4.0+
 # This must be loaded before any YARD code is required
 require_relative 'yard/lint/ext/irb_notifier_shim'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.3.0.rc1
+  version: 1.4.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -47,6 +47,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".coditsu/ci.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -142,6 +143,12 @@ files:
 - lib/yard/lint/validators/tags/example_syntax/parser.rb
 - lib/yard/lint/validators/tags/example_syntax/result.rb
 - lib/yard/lint/validators/tags/example_syntax/validator.rb
+- lib/yard/lint/validators/tags/forbidden_tags.rb
+- lib/yard/lint/validators/tags/forbidden_tags/config.rb
+- lib/yard/lint/validators/tags/forbidden_tags/messages_builder.rb
+- lib/yard/lint/validators/tags/forbidden_tags/parser.rb
+- lib/yard/lint/validators/tags/forbidden_tags/result.rb
+- lib/yard/lint/validators/tags/forbidden_tags/validator.rb
 - lib/yard/lint/validators/tags/informal_notation.rb
 - lib/yard/lint/validators/tags/informal_notation/config.rb
 - lib/yard/lint/validators/tags/informal_notation/messages_builder.rb
@@ -259,7 +266,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.0.dev
 specification_version: 4
 summary: YARD documentation linter and validator
 test_files: []