yard-lint 1.0.0 → 1.1.0

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

@@ -4,7 +4,37 @@ module Yard
   module Lint
     module Validators
       module Semantic
-        # AbstractMethods validator module
+        # AbstractMethods validator
+        #
+        # Ensures that methods marked with `@abstract` are actually abstract (not
+        # implemented). Abstract methods should either raise NotImplementedError or
+        # be empty stubs, not contain actual implementation logic. This validator
+        # is enabled by default.
+        #
+        # @example Bad - @abstract tag on implemented method
+        #   # @abstract
+        #   def process
+        #     puts "This is actually implemented!"
+        #   end
+        #
+        # @example Good - @abstract method raises NotImplementedError
+        #   # @abstract
+        #   def process
+        #     raise NotImplementedError
+        #   end
+        #
+        # @example Good - @abstract method is empty
+        #   # @abstract
+        #   def process
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Semantic/AbstractMethods:
+        #       Enabled: false
+        #
         module AbstractMethods
         end
       end

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

@@ -4,7 +4,40 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # ApiTags validator module
+        # ApiTags validator
+        #
+        # Enforces that all public classes, modules, and methods have an `@api` tag
+        # to explicitly document their API visibility level. This validator is disabled
+        # by default and must be explicitly enabled.
+        #
+        # ## Configuration
+        #
+        # To enable this validator (it's disabled by default):
+        #
+        #     Tags/ApiTags:
+        #       Enabled: true
+        #       AllowedApis:
+        #         - public
+        #         - private
+        #
+        # @example Good - Methods and classes have @api tags
+        #   # @api public
+        #   class MyClass
+        #     # @api public
+        #     def public_method
+        #     end
+        #
+        #     # @api private
+        #     def internal_helper
+        #     end
+        #   end
+        #
+        # @example Bad - Missing @api tags
+        #   class AnotherClass
+        #     def some_method
+        #     end
+        #   end
+        #
         module ApiTags
         end
       end

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

@@ -11,7 +11,8 @@ module Yard
             self.defaults = {
               'Enabled' => true,
               'Severity' => 'convention',
-              'ValidatedTags' => %w[param option return yieldreturn]
+              'ValidatedTags' => %w[param option return yieldreturn],
+              'EnforcedStyle' => 'long' # 'long' (Hash{K => V}) or 'short' ({K => V})
             }.freeze
           end
         end

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

@@ -14,27 +14,56 @@ module Yard
               def call(offense)
                 type_string = offense[:type_string]
                 tag_name = offense[:tag_name]
+                detected_style = offense[:detected_style]
 
-                # Extract the corrected version
-                corrected = suggest_correction(type_string)
+                # Extract the corrected version based on detected style
+                corrected = suggest_correction(type_string, detected_style)
+                style_description = detected_style == 'short' ? 'long' : 'short'
 
-                "Use YARD collection syntax #{corrected} instead of #{type_string} " \
-                  "in @#{tag_name} tag. YARD uses Hash{K => V} syntax for hashes."
+                "Use #{style_description} collection syntax #{corrected} instead of " \
+                  "#{type_string} in @#{tag_name} tag."
               end
 
               private
 
-              # Suggests the corrected YARD syntax
+              # Suggests the corrected YARD syntax based on detected style
               # @param type_string [String] the incorrect type string
+              # @param detected_style [String] the detected style ('short' or 'long')
               # @return [String] the suggested correction
-              def suggest_correction(type_string)
-                # Convert Hash<K, V> to Hash{K => V}
-                type_string.gsub(/Hash<(.+?)>/) do
-                  types = ::Regexp.last_match(1)
-                  # Split on comma, handle nested types
-                  "Hash{#{types.sub(/,\s*/, ' => ')}}"
+              def suggest_correction(type_string, detected_style)
+                if detected_style == 'short'
+                  # Convert short to long: Hash<K, V> -> Hash{K => V} or {K => V} -> Hash{K => V}
+                  convert_to_long(type_string)
+                else
+                  # Convert long to short: Hash{K => V} -> {K => V}
+                  convert_to_short(type_string)
                 end
               end
+
+              # Converts short syntax to long syntax
+              # @param type_string [String] the type string
+              # @return [String] the converted type string
+              def convert_to_long(type_string)
+                if type_string.start_with?('{')
+                  # {K => V} -> Hash{K => V}
+                  "Hash#{type_string}"
+                else
+                  # Hash<K, V> -> Hash{K => V}
+                  type_string.gsub(/Hash<(.+?)>/) do
+                    types = ::Regexp.last_match(1)
+                    # Split on comma, handle nested types
+                    "Hash{#{types.sub(/,\s*/, ' => ')}}"
+                  end
+                end
+              end
+
+              # Converts long syntax to short syntax
+              # @param type_string [String] the type string
+              # @return [String] the converted type string
+              def convert_to_short(type_string)
+                # Hash{K => V} -> {K => V}
+                type_string.sub(/^Hash/, '')
+              end
             end
           end
         end

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

@@ -24,18 +24,19 @@ module Yard
                 location_match = location_line.match(/^(.+):(\d+): (.+)$/)
                 next unless location_match
 
-                # Parse details: "tag_name|type_string"
-                details = details_line.split('|', 2)
-                next unless details.size == 2
+                # Parse details: "tag_name|type_string|detected_style"
+                details = details_line.split('|', 3)
+                next unless details.size == 3
 
-                tag_name, type_string = details
+                tag_name, type_string, detected_style = details
 
                 violations << {
                   location: location_match[1],
                   line: location_match[2].to_i,
                   object_name: location_match[3],
                   tag_name: tag_name,
-                  type_string: type_string
+                  type_string: type_string,
+                  detected_style: detected_style
                 }
               end
 

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

@@ -28,12 +28,14 @@ module Yard
               end
             end
 
-            # YARD query that finds Hash<K, V> syntax in type annotations
+            # YARD query that finds incorrect collection syntax based on EnforcedStyle
             # Format output as two lines per violation:
             #   Line 1: file.rb:LINE: ClassName#method_name
-            #   Line 2: tag_name|type_string
+            #   Line 2: tag_name|type_string|detected_style
             # @return [String] YARD query string
             def query
+              style = enforced_style
+
               <<~QUERY.strip
                 '
                 docstring
@@ -43,10 +45,23 @@ module Yard
                     next unless tag.types
 
                     tag.types.each do |type_str|
-                      # Check for Hash<...> syntax (should be Hash{...})
+                      detected_style = nil
+
+                      # Check for Hash<...> syntax (angle brackets)
                       if type_str =~ /Hash<.*>/
+                        detected_style = "short"
+                      # Check for Hash{...} syntax (curly braces)
+                      elsif type_str =~ /Hash\\{.*\\}/
+                        detected_style = "long"
+                      # Check for {...} syntax without Hash prefix
+                      elsif type_str =~ /^\\{.*\\}$/
+                        detected_style = "short"
+                      end
+
+                      # Report violations based on enforced style
+                      if detected_style && detected_style != "#{style}"
                         puts object.file + ":" + object.line.to_s + ": " + object.title
-                        puts tag.tag_name + "|" + type_str
+                        puts tag.tag_name + "|" + type_str + "|" + detected_style
                         break
                       end
                     end
@@ -57,12 +72,16 @@ module Yard
               QUERY
             end
 
+            # Gets the enforced collection style from configuration
+            # @return [String] 'long' or 'short'
+            def enforced_style
+              config_or_default('EnforcedStyle')
+            end
+
             # Array of tag names to validate, formatted for YARD query
             # @return [String] Ruby array literal string
             def validated_tags_array
-              tags = config.validator_config('Tags/CollectionType', 'ValidatedTags') || %w[
-                param option return yieldreturn
-              ]
+              tags = config_or_default('ValidatedTags')
               "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
             end
           end

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

@@ -4,8 +4,44 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # CollectionType validator module
-        # Detects incorrect Hash collection syntax (Hash<K, V> instead of Hash{K => V})
+        # CollectionType validator
+        #
+        # Enforces correct YARD collection type syntax for Hash types. YARD uses
+        # `Hash{K => V}` syntax with curly braces and hash rockets, not the generic
+        # `Hash<K, V>` syntax used in other languages and documentation tools.
+        # This validator is enabled by default.
+        #
+        # ## Why This Matters
+        #
+        # YARD has specific syntax conventions that differ from other documentation tools.
+        # Using the correct syntax ensures that YARD can properly parse and display your
+        # type annotations in generated documentation.
+        #
+        # @example Bad - Generic syntax with angle brackets
+        #   # @param options [Hash<Symbol, String>] configuration options
+        #   # @param mapping [Hash<String, Integer>] key to value mapping
+        #   def configure(options, mapping)
+        #   end
+        #
+        # @example Good - YARD syntax with curly braces
+        #   # @param options [Hash{Symbol => String}] configuration options
+        #   # @param mapping [Hash{String => Integer}] key to value mapping
+        #   def configure(options, mapping)
+        #   end
+        #
+        # @example Good - Arrays use angle brackets (correct for YARD)
+        #   # @param items [Array<String>] list of items
+        #   # @param numbers [Array<Integer>] list of numbers
+        #   def process(items, numbers)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/CollectionType:
+        #       Enabled: false
+        #
         module CollectionType
         end
       end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleSyntax
+          # Configuration for ExampleSyntax validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :example_syntax
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleSyntax
+          # Builds messages for example syntax offenses
+          class MessagesBuilder
+            class << self
+              # Build message for example syntax offense
+              # @param offense [Hash] offense data with :example_name and :error_message keys
+              # @return [String] formatted message
+              def call(offense)
+                example_name = offense[:example_name]
+                error_msg = offense[:error_message]
+                object_name = offense[:object_name]
+
+                "Object `#{object_name}` has syntax error in @example " \
+                  "'#{example_name}': #{error_msg}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleSyntax
+          # Parser for @example syntax validation results
+          class Parser < Parsers::Base
+            # @param yard_output [String] raw yard output with example syntax issues
+            # @return [Array<Hash>] array with example syntax violation details
+            def call(yard_output)
+              return [] if yard_output.nil? || yard_output.empty?
+
+              lines = yard_output.split("\n").reject(&:empty?)
+              results = []
+
+              # Output format is variable lines per error:
+              # 1. file.rb:10: ClassName#method_name
+              # 2. syntax_error
+              # 3. Example name
+              # 4+. Error message (can be multiple lines)
+              # Next error starts with another file.rb:line: pattern
+
+              i = 0
+              while i < lines.length
+                location_line = lines[i]
+
+                # Parse location line: "file.rb:10: ClassName#method_name"
+                # File paths typically start with a letter or . or / or ~
+                match = location_line.match(%r{^([a-zA-Z./~].+):(\d+): (.+)$})
+                unless match
+                  i += 1
+                  next
+                end
+
+                file = match[1]
+                line = match[2].to_i
+                object_name = match[3]
+
+                # Next line should be status
+                i += 1
+                status_line = lines[i]
+                next unless status_line == 'syntax_error'
+
+                # Next line is example name
+                i += 1
+                example_name = lines[i]
+
+                # Collect all remaining lines until we hit the next location line or end
+                error_message_lines = []
+                i += 1
+                while i < lines.length
+                  # Check if this line starts a new error (matches file:line: pattern)
+                  # File paths typically start with a letter or . or / or ~
+                  break if lines[i].match?(%r{^[a-zA-Z./~].+:\d+: .+$})
+
+                  error_message_lines << lines[i]
+                  i += 1
+                end
+
+                results << {
+                  name: 'ExampleSyntax',
+                  object_name: object_name,
+                  example_name: example_name,
+                  error_message: error_message_lines.join("\n"),
+                  location: file,
+                  line: line
+                }
+              end
+
+              results
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleSyntax
+          # Result object for example syntax validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'ExampleSyntaxError'
+
+            # Build human-readable message for example syntax offense
+            # @param offense [Hash] offense data with :example_name and :error_message keys
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+
+            private
+
+            # Override to build offenses with dynamic names from parsed data
+            # @return [Array<Hash>] array of offense hashes
+            def build_offenses
+              @parsed_data.map do |offense_data|
+                {
+                  severity: configured_severity,
+                  type: self.class.offense_type,
+                  name: offense_data[:name] || self.class.offense_name,
+                  message: build_message(offense_data),
+                  location: offense_data[:location] || offense_data[:file],
+                  location_line: offense_data[:line] || offense_data[:location_line] || 0
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleSyntax
+          # Validator to check syntax of code in @example tags
+          class Validator < Base
+            private
+
+            # Runs yard list query to find objects with invalid syntax in @example tags
+            # @param dir [String] dir where the yard db is (or where it should be generated)
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
+            # @return [Hash] shell command execution hash results
+            def yard_cmd(dir, file_list_path)
+              cmd = <<~CMD
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
+                --private \
+                --protected \
+                -b #{Shellwords.escape(dir)}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+              cmd = cmd.gsub('yard list', "yard list --query #{query}")
+
+              shell(cmd)
+            end
+
+            # @return [String] yard query to find @example tags with syntax errors
+            def query
+              <<~QUERY
+                '
+                  if object.has_tag?(:example)
+                    example_tags = object.tags(:example)
+
+                    example_tags.each_with_index do |example, index|
+                      code = example.text
+                      next if code.nil? || code.empty?
+
+                      # Clean the code: strip output indicators (#=>) and everything after it
+                      code_lines = code.split("\\n").map do |line|
+                        line.sub(/\\s*#\\s*=>.*$/, "")
+                      end
+
+                      cleaned_code = code_lines.join("\\n").strip
+                      next if cleaned_code.empty?
+
+                      # Check if code looks incomplete (single expression without context)
+                      # Skip validation for these cases
+                      lines = cleaned_code.split("\\n").reject { |l| l.strip.empty? || l.strip.start_with?("#") }
+
+                      # Skip if it is a single line that looks like an incomplete expression
+                      if lines.size == 1
+                        line = lines.first.strip
+                        # Skip method calls, variable references, or simple expressions
+                        # These are likely incomplete snippets showing usage
+                        if line.match?(/^[a-z_][a-z0-9_]*(\\.| |$)/) || line.match?(/^[A-Z]/) && !line.match?(/^(class|module|def)\\s/)
+                          next
+                        end
+                      end
+
+                      # Try to parse the code
+                      begin
+                        RubyVM::InstructionSequence.compile(cleaned_code)
+                      rescue SyntaxError => e
+                        # Report syntax errors
+                        example_name = example.name || "Example " + (index + 1).to_s
+                        puts object.file + ":" + object.line.to_s + ": " + object.title
+                        puts "syntax_error"
+                        puts example_name
+                        puts e.message
+                      rescue => e
+                        # Other errors (like NameError, ArgumentError) are fine
+                        # We only check syntax, not semantics
+                        next
+                      end
+                    end
+                  end
+                  false
+                '
+              QUERY
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Tags validators - validate YARD tag quality and consistency
+      module Tags
+        # ExampleSyntax validator
+        #
+        # Validates Ruby syntax in `@example` tags using RubyVM::InstructionSequence.compile().
+        # This validator ensures that code examples in documentation are syntactically valid.
+        # It automatically strips output indicators (`#=>`) and skips incomplete single-line
+        # snippets. This validator is enabled by default.
+        #
+        # @example Bad - Invalid Ruby syntax in example
+        #   # @example
+        #   #   def broken(
+        #   #     # missing closing
+        #   def my_method
+        #   end
+        #
+        # @example Good - Valid Ruby syntax in example
+        #   # @example
+        #   #   def my_method(name)
+        #   #     puts name
+        #   #   end
+        #   def my_method(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/ExampleSyntax:
+        #       Enabled: false
+        #
+        module ExampleSyntax
+        end
+      end
+    end
+  end
+end

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

@@ -77,14 +77,14 @@ module Yard
             # @return [String] tags names for which we want to check the invalid tags
             #   types definitions
             def checked_tags_names
-              validated_tags = config.validator_config('Tags/InvalidTypes', 'ValidatedTags')
+              validated_tags = config_or_default('ValidatedTags')
               query_array(validated_tags)
             end
 
             # @return [String] extra names that we allow for types definitions in a yard
             #   query acceptable form
             def allowed_types_code
-              extra_types = config.validator_config('Tags/InvalidTypes', 'ExtraTypes') || []
+              extra_types = config_or_default('ExtraTypes')
               query_array(ALLOWED_DEFAULTS + extra_types)
             end
 

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

@@ -4,7 +4,31 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # InvalidTypes validator module
+        # InvalidTypes validator
+        #
+        # Detects invalid or malformed type annotations in YARD tags. This validator
+        # checks that type specifications follow YARD's type syntax rules and that
+        # type names are valid. This validator is enabled by default.
+        #
+        # @example Bad - Invalid type syntax
+        #   # @param name [String | Integer] the name (wrong pipe syntax)
+        #   # @return [Array[String]] invalid nested syntax
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Valid type syntax
+        #   # @param name [String, Integer] the name (comma-separated union)
+        #   # @return [Array<String>] valid nested syntax
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/InvalidTypes:
+        #       Enabled: false
+        #
         module InvalidTypes
         end
       end

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

@@ -67,14 +67,12 @@ module Yard
 
             # @return [Array<String>] tags that should only appear on methods
             def checked_tags
-              config.validator_config('Tags/MeaninglessTag', 'CheckedTags') || %w[param option]
+              config_or_default('CheckedTags')
             end
 
             # @return [Array<String>] object types that shouldn't have method-only tags
             def invalid_object_types
-              config.validator_config('Tags/MeaninglessTag', 'InvalidObjectTypes') || %w[
-                class module constant
-              ]
+              config_or_default('InvalidObjectTypes')
             end
           end
         end