yard-lint 1.0.0 → 1.2.0

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedOptions
+          # Parses YARD output for undocumented options violations
+          class Parser < Parsers::Base
+            # Parse YARD output into structured violations
+            # @param output [String] raw YARD 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
+                line = lines[i]
+
+                # Match location line: "file:line: object_name"
+                if (location_match = line.match(/^(.+):(\d+): (.+)$/))
+                  file_path = location_match[1]
+                  line_number = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  # Next line contains parameter list
+                  i += 1
+                  next unless i < lines.size
+
+                  params = lines[i]
+
+                  violations << {
+                    location: file_path,
+                    line: line_number,
+                    object_name: object_name,
+                    params: params
+                  }
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedOptions
+          # Result object for undocumented options validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'UndocumentedOptions'
+
+            # Build human-readable message for undocumented options offense
+            # @param offense [Hash] offense data with :object_name and :params
+            # @return [String] formatted message
+            def build_message(offense)
+              object_name = offense[:object_name]
+              params = offense[:params]
+
+              "Method '#{object_name}' has options parameter (#{params}) " \
+                'but no @option tags in documentation.'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedOptions
+          # Validates that methods with options hash parameters have @option tags
+          class Validator < Validators::Base
+            # YARD query to detect methods with options parameters but no @option tags
+            # @return [String] YARD Ruby query code
+            def query
+              <<~QUERY.strip
+                'if object.is_a?(YARD::CodeObjects::MethodObject); params = object.parameters || []; has_options_param = params.any? { |p| p[0] =~ /^(options?|opts?|kwargs)$/ || p[0] =~ /^\\*\\*/ || (p[0] =~ /^(options?|opts?|kwargs)$/ && p[1] =~ /^\\{\\}/) }; if has_options_param; option_tags = object.tags(:option); if option_tags.empty?; puts object.file + ":" + object.line.to_s + ": " + object.title; puts params.map { |p| p.join(" ") }.join(", "); end; end; end; false'
+              QUERY
+            end
+
+            # Builds and executes the YARD command to detect undocumented options
+            # @param dir [String] the directory containing the .yardoc database
+            # @param file_list_path [String] path to file containing list of files to analyze
+            # @return [String] command output
+            def yard_cmd(dir, file_list_path)
+              cmd = <<~CMD
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
+                  #{shell_arguments} \
+                --query #{query} \
+                -q \
+                -b #{Shellwords.escape(dir)}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # UndocumentedOptions validator
+        #
+        # Checks that options hashes have detailed documentation about their keys.
+        # When a method accepts an options hash parameter, the individual option
+        # keys should be documented using `@option` tags. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Options parameter without @option tags
+        #   # Configures the service
+        #   # @param options [Hash] configuration options
+        #   def configure(options)
+        #   end
+        #
+        # @example Good - Options keys documented with @option tags
+        #   # Configures the service
+        #   # @param options [Hash] configuration options
+        #   # @option options [Boolean] :enabled Whether to enable the feature
+        #   # @option options [Integer] :timeout Connection timeout in seconds
+        #   def configure(options)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/UndocumentedOptions:
+        #       Enabled: false
+        #
+        module UndocumentedOptions
+        end
+      end
+    end
+  end
+end

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