yard-lint 0.2.1 → 1.1.0

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module CollectionType
+          # Validates Hash collection type syntax in YARD tags
+          class Validator < Base
+            private
+
+            # Runs YARD query to find incorrect Hash<K, V> syntax
+            # @param dir [String] directory where YARD database is stored
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
+            # @return [Hash] shell command execution results
+            def yard_cmd(dir, file_list_path)
+              # Write query to a temporary file to avoid shell escaping issues
+              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{query} "
+
+              Tempfile.create(['yard_query', '.sh']) do |f|
+                f.write("#!/bin/bash\n")
+                f.write(cmd)
+                f.write("#{shell_arguments} -b #{Shellwords.escape(dir)}\n")
+                f.flush
+                f.chmod(0o755)
+
+                shell("bash #{Shellwords.escape(f.path)}")
+              end
+            end
+
+            # 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|detected_style
+            # @return [String] YARD query string
+            def query
+              style = enforced_style
+
+              <<~QUERY.strip
+                '
+                docstring
+                  .tags
+                  .select { |tag| #{validated_tags_array}.include?(tag.tag_name) }
+                  .each do |tag|
+                    next unless tag.types
+
+                    tag.types.each do |type_str|
+                      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 + "|" + detected_style
+                        break
+                      end
+                    end
+                  end
+
+                false
+                '
+              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_or_default('ValidatedTags')
+              "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # 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
+    end
+  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

@@ -24,17 +24,17 @@ module Yard
 
             # Runs yard list query with proper settings on a given dir and files
             # @param dir [String] dir where the yard db is (or where it should be generated)
-            # @param escaped_file_names [String] files for which we want to get the stats
+            # @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, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               # Write query to a temporary file to avoid shell escaping issues
-              require 'tempfile'
+              squery = Shellwords.escape(query)
+              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{squery} "
 
               Tempfile.create(['yard_query', '.sh']) do |f|
                 f.write("#!/bin/bash\n")
-                f.write("yard list --query #{Shellwords.escape(query)} ")
-                f.write("--private --protected -b #{Shellwords.escape(dir)} ")
-                f.write("#{escaped_file_names}\n")
+                f.write(cmd)
+                f.write("--private --protected -b #{Shellwords.escape(dir)}\n")
                 f.flush
                 f.chmod(0o755)
 
@@ -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/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Configuration for MeaninglessTag validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :meaningless_tag
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning',
+              'CheckedTags' => %w[param option],
+              'InvalidObjectTypes' => %w[class module constant]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Builds human-readable messages for MeaninglessTag violations
+          class MessagesBuilder
+            class << self
+              # Formats a meaningless tag violation message
+              # @param offense [Hash] offense details with :object_type, :tag_name, :object_name
+              # @return [String] formatted message
+              def call(offense)
+                object_type = offense[:object_type]
+                tag_name = offense[:tag_name]
+                object_name = offense[:object_name]
+
+                "The @#{tag_name} tag is meaningless on a #{object_type} " \
+                  "(#{object_name}). This tag only makes sense on methods."
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Parser for MeaninglessTag validator output
+          # Parses YARD query output that reports meaningless tags on non-methods
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses YARD output and extracts meaningless tag violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ClassName
+            #   object_type|tag_name
+            # @param yard_output [String] raw YARD query results
+            # @param _kwargs [Hash] unused keyword arguments (for compatibility)
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **_kwargs)
+              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
+
+                # Parse location: "file.rb:10: ClassName"
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # Parse details: "object_type|tag_name"
+                details = details_line.split('|', 2)
+                next unless details.size == 2
+
+                object_type, tag_name = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  object_type: object_type,
+                  tag_name: tag_name
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Result wrapper for MeaninglessTag validator
+          # Formats parsed violations into offense objects
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'class'
+            self.offense_name = 'MeaninglessTag'
+
+            # 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