yard-lint 1.3.0 → 1.5.0

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # ExampleStyle validator
+        #
+        # Validates code style in `@example` tags using RuboCop or StandardRB.
+        # This validator ensures that code examples follow the same style guidelines
+        # as the project codebase for consistency.
+        #
+        # ## Requirements
+        #
+        # - RuboCop or StandardRB gem must be installed
+        # - Validator auto-detects which linter to use based on project setup
+        #
+        # ## Configuration
+        #
+        # Basic usage:
+        #
+        #     Tags/ExampleStyle:
+        #       Enabled: true
+        #
+        # Advanced configuration:
+        #
+        #     Tags/ExampleStyle:
+        #       Enabled: true
+        #       Linter: auto  # 'auto', 'rubocop', 'standard', or 'none'
+        #       SkipPatterns:
+        #         - '/skip-lint/i'
+        #         - '/bad code/i'
+        #       DisabledCops:
+        #         - 'Metrics/MethodLength'
+        #
+        # ## Skipping Examples
+        #
+        # Skip linting for specific examples (negative examples):
+        #
+        #     # @example Bad code (skip-lint)
+        #     #   user = User.new("invalid")
+        #
+        # Or use inline RuboCop directives:
+        #
+        #     # @example
+        #     #   # rubocop:disable all
+        #     #   user = User.new("invalid")
+        #     #   # rubocop:enable all
+        module ExampleStyle
+          autoload :Validator, 'yard/lint/validators/tags/example_style/validator'
+          autoload :Config, 'yard/lint/validators/tags/example_style/config'
+          autoload :Parser, 'yard/lint/validators/tags/example_style/parser'
+          autoload :Result, 'yard/lint/validators/tags/example_style/result'
+          autoload :MessagesBuilder, 'yard/lint/validators/tags/example_style/messages_builder'
+          autoload :LinterDetector, 'yard/lint/validators/tags/example_style/linter_detector'
+          autoload :RubocopRunner, 'yard/lint/validators/tags/example_style/rubocop_runner'
+        end
+      end
+    end
+  end
+end

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/validators/tags/invalid_types/validator.rb

@@ -34,7 +34,7 @@ module Yard
               allowed_types = ALLOWED_DEFAULTS + extra_types
 
               # Sanitize type string (remove type syntax characters)
-              sanitize = ->(type) { type.tr('=><>,{} ', '') }
+              sanitize = ->(type) { type.tr('=><>,{} ()', '') }
 
               # Check for invalid types
               invalid_types = object.docstring.tags

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

@@ -7,7 +7,7 @@ module Yard
         module TagGroupSeparator
           # Parser for extracting tag group separator violations from raw validator output.
           #
-          # @example Output format
+          # @example Output format (skip-lint)
           #   /path/to/file.rb:10: ClassName#method_name
           #   param->return,return->error
           class Parser < Parsers::Base

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

@@ -7,6 +7,18 @@ module Yard
         module TypeSyntax
           # Runs YARD to validate type syntax using TypesExplainer::Parser
           class Validator < Base
+            # Matches valid Ruby symbol literals: :foo, :foo?, :foo!, :foo=
+            SYMBOL_LITERAL = /\A:[a-zA-Z_]\w*[?!=]?\z/
+            # Matches valid quoted symbol literals: :"foo", :'foo' (quotes must match)
+            QUOTED_SYMBOL_LITERAL = /\A:("[^"]*"|'[^']*')\z/
+            # Matches string literals: "foo", 'foo' (quotes must match)
+            STRING_LITERAL = /\A("[^"]*"|'[^']*')\z/
+            # Matches numeric literals: 1, -1, 1.0, -2.5
+            NUMERIC_LITERAL = /\A-?\d+(\.\d+)?\z/
+
+            private_constant :SYMBOL_LITERAL, :QUOTED_SYMBOL_LITERAL, :STRING_LITERAL,
+                             :NUMERIC_LITERAL
+
             # Enable in-process execution
             in_process visibility: :public
 
@@ -25,6 +37,13 @@ module Yard
                 next unless tag.types
 
                 tag.types.each do |type_str|
+                  # Skip literal types that YARD accepts but TypesExplainer::Parser doesn't
+                  # See: https://github.com/mensfeld/yard-lint/issues/109
+                  next if type_str.match?(SYMBOL_LITERAL)
+                  next if type_str.match?(QUOTED_SYMBOL_LITERAL)
+                  next if type_str.match?(STRING_LITERAL)
+                  next if type_str.match?(NUMERIC_LITERAL)
+
                   begin
                     YARD::Tags::TypesExplainer::Parser.parse(type_str)
                   rescue SyntaxError => e

data/lib/yard/lint/validators/warnings/unknown_tag/parser.rb

@@ -6,7 +6,7 @@ module Yard
       module Warnings
         module UnknownTag
           # Parser used to extract warnings details that are related to yard unknown tags
-          # @example
+          # @example Output format (skip-lint)
           #   [warn]: Unknown tag @example1 in file `/builds/path/engine.rb` near line 32
           class Parser < ::Yard::Lint::Parsers::OneLineBase
             # Set of regexps for detecting warnings reported by YARD stats

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'
+    VERSION = '1.5.0'
   end
 end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.3.0"