yard-lint 1.3.0 → 1.5.0

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

@@ -5,13 +5,13 @@ module Yard
     module Validators
       module Tags
         module CollectionType
-          # Validates Hash collection type syntax in YARD tags
+          # Validates Hash and Array collection type syntax in YARD tags
           class Validator < Base
             # Enable in-process execution
             in_process visibility: :public
 
             # Execute query for a single object during in-process execution.
-            # Validates Hash collection type syntax based on EnforcedStyle.
+            # Validates collection type syntax based on EnforcedStyle.
             # @param object [YARD::CodeObjects::Base] the code object to query
             # @param collector [Executor::ResultCollector] collector for output
             # @return [void]
@@ -25,18 +25,7 @@ module Yard
                 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
+                  detected_style = detect_style(type_str)
 
                   # Report violations based on enforced style
                   if detected_style && detected_style != style
@@ -50,6 +39,36 @@ module Yard
 
             private
 
+            # Detects the collection style used in a type string
+            # @param type_str [String] the type string to check
+            # @return [String, nil] 'long' or 'short', or nil if not a collection type
+            def detect_style(type_str)
+              # Hash types
+              # Hash<...> is short style (should be Hash{K => V})
+              if type_str =~ /Hash<.*>/
+                'short'
+              # Hash{...} is long style
+              elsif type_str =~ /Hash\{.*\}/
+                'long'
+              # {...} without Hash prefix is short style
+              elsif type_str =~ /^\{.*\}$/
+                'short'
+              # Array types
+              # Array<...> is long style
+              elsif type_str =~ /Array<.*>/
+                'long'
+              # Array(...) is long style
+              elsif type_str =~ /Array\(.*\)/
+                'long'
+              # <...> without Array prefix is short style
+              elsif type_str =~ /^<.*>$/
+                'short'
+              # (...) without Array prefix is short style (tuple shorthand)
+              elsif type_str =~ /^\(.*\)$/
+                'short'
+              end
+            end
+
             # Gets the enforced collection style from configuration
             # @return [String] 'long' or 'short'
             def enforced_style

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleStyle
+          # Configuration for ExampleStyle validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :example_style
+            self.defaults = {
+              'Enabled' => false,  # Opt-in validator
+              'Severity' => 'convention',
+              'Linter' => 'auto',  # 'auto', 'rubocop', 'standard', or 'none'
+              'SkipPatterns' => [],
+              'DisabledCops' => [
+                # File-level cops that don't make sense for code snippets
+                'Style/FrozenStringLiteralComment',
+                'Layout/TrailingWhitespace',
+                'Layout/EndOfLine',
+                'Layout/TrailingEmptyLines',
+                'Metrics/MethodLength',
+                'Metrics/AbcSize',
+                'Metrics/CyclomaticComplexity',
+                'Metrics/PerceivedComplexity'
+              ]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleStyle
+          # Detects available linters (RuboCop or StandardRB) in the project
+          class LinterDetector
+            class << self
+              # Detect which linter to use based on configuration and project setup
+              # @param config_linter [String] configured linter preference ('auto', 'rubocop', 'standard', 'none')
+              # @param project_root [String] project root directory for file checks
+              # @return [Symbol] detected linter (:rubocop, :standard, or :none)
+              def detect(config_linter, project_root: Dir.pwd)
+                return :none if config_linter == 'none'
+                return :rubocop if config_linter == 'rubocop' && rubocop_available?
+                return :standard if config_linter == 'standard' && standard_available?
+
+                # Auto-detection logic
+                return :none unless config_linter == 'auto'
+
+                # Priority 1: Check for .standard.yml config file
+                return :standard if File.exist?(File.join(project_root, '.standard.yml')) && standard_available?
+
+                # Priority 2: Check for .rubocop.yml config file
+                return :rubocop if File.exist?(File.join(project_root, '.rubocop.yml')) && rubocop_available?
+
+                # Priority 3: Check Gemfile for 'standard' gem
+                gemfile_path = File.join(project_root, 'Gemfile')
+                if File.exist?(gemfile_path)
+                  gemfile_content = File.read(gemfile_path)
+                  return :standard if gemfile_content.match?(/gem\s+['"]standard['"]/) && standard_available?
+                  return :rubocop if gemfile_content.match?(/gem\s+['"]rubocop['"]/) && rubocop_available?
+                end
+
+                # Priority 4: Check for Gemfile.lock
+                gemfile_lock_path = File.join(project_root, 'Gemfile.lock')
+                if File.exist?(gemfile_lock_path)
+                  lock_content = File.read(gemfile_lock_path)
+                  return :standard if lock_content.include?('standard (') && standard_available?
+                  return :rubocop if lock_content.include?('rubocop (') && rubocop_available?
+                end
+
+                :none
+              end
+
+              # Check if RuboCop gem is available
+              # @return [Boolean] true if RuboCop can be loaded
+              def rubocop_available?
+                require 'rubocop'
+                true
+              rescue LoadError
+                false
+              end
+
+              # Check if StandardRB gem is available
+              # @return [Boolean] true if StandardRB can be loaded
+              def standard_available?
+                require 'standard'
+                true
+              rescue LoadError
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleStyle
+          # Parser for @example style validation results
+          class Parser < Parsers::Base
+            # @param yard_output [String] raw yard output with example style issues
+            # @return [Array<Hash>] array with example style violation details
+            def call(yard_output)
+              return [] if yard_output.nil? || yard_output.empty?
+
+              # Normalize line endings (handle Windows \r\n)
+              normalized_output = yard_output.gsub("\r\n", "\n")
+              lines = normalized_output.split("\n").reject(&:empty?)
+              results = []
+
+              # Output format is exactly 5 lines per offense:
+              # 1. file.rb:10: ClassName#method_name
+              # 2. style_offense
+              # 3. Example name
+              # 4. Cop name (e.g., Style/StringLiterals)
+              # 5. Offense message
+              # Next offense 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"
+                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
+                break if i >= lines.length
+
+                status_line = lines[i]
+                next unless status_line == 'style_offense'
+
+                # Next line is example name
+                i += 1
+                break if i >= lines.length
+
+                example_name = lines[i]
+
+                # Next line is cop name
+                i += 1
+                break if i >= lines.length
+
+                cop_name = lines[i]
+
+                # Next line is message
+                i += 1
+                break if i >= lines.length
+
+                message = lines[i]
+
+                results << {
+                  name: 'ExampleStyle',
+                  object_name: object_name,
+                  example_name: example_name,
+                  cop_name: cop_name,
+                  message: message,
+                  location: file,
+                  line: line
+                }
+
+                i += 1
+              end
+
+              results
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleStyle
+          # Result object for example style validation
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'line'
+            self.offense_name = 'ExampleStyleOffense'
+
+            # Build human-readable message for example style offense
+            # @param offense [Hash] offense data with :example_name, :cop_name, :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_style/rubocop_runner.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'json'
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleStyle
+          # Runs RuboCop or StandardRB on code snippets and returns offenses
+          class RubocopRunner
+            # @param linter [Symbol] which linter to use (:rubocop or :standard)
+            # @param disabled_cops [Array<String>] list of cop names to disable
+            # @param skip_patterns [Array<String>] regex patterns to skip examples
+            def initialize(linter:, disabled_cops: [], skip_patterns: [])
+              @linter = linter
+              @disabled_cops = disabled_cops
+              @skip_patterns = compile_patterns(skip_patterns)
+            end
+
+            # Run linter on code example and return offenses
+            # @param code [String] Ruby code extracted from @example tag to check for style violations
+            # @param example_name [String] name of the example for context
+            # @param file_path [String] path to the file being linted (for config discovery)
+            # @return [Array<Hash>] array of offense hashes with :cop_name, :message, :line, :column keys
+            def run(code, example_name, file_path: nil)
+              return [] if should_skip?(example_name)
+
+              cleaned_code = clean_code(code)
+              return [] if cleaned_code.empty?
+
+              case @linter
+              when :rubocop
+                run_rubocop(cleaned_code, file_path: file_path)
+              when :standard
+                run_standard(cleaned_code, file_path: file_path)
+              else
+                []
+              end
+            rescue StandardError => e
+              warn "[YARD::Lint] ExampleStyle: Error running #{@linter}: #{e.message}" if ENV['DEBUG']
+              []
+            end
+
+            private
+
+            # Compile skip patterns into regex objects
+            # @param patterns [Array<String>] array of regex pattern strings
+            # @return [Array<Regexp>] array of compiled regex objects
+            def compile_patterns(patterns)
+              patterns.filter_map do |pattern|
+                # Pattern format: '/pattern/flags' or 'pattern'
+                if pattern.start_with?('/') && pattern.match?(%r{^/(.+)/([imx]*)$})
+                  match = pattern.match(%r{^/(.+)/([imx]*)$})
+                  Regexp.new(match[1], parse_flags(match[2]))
+                else
+                  Regexp.new(pattern)
+                end
+              rescue RegexpError => e
+                warn "[YARD::Lint] ExampleStyle: Invalid skip pattern '#{pattern}': #{e.message}" if ENV['DEBUG']
+                nil
+              end
+            end
+
+            # Parse regex flags from string
+            # @param flags_str [String] flags string like 'i' or 'im'
+            # @return [Integer] OR'd flag constants
+            def parse_flags(flags_str)
+              flags = 0
+              flags |= Regexp::IGNORECASE if flags_str.include?('i')
+              flags |= Regexp::MULTILINE if flags_str.include?('m')
+              flags |= Regexp::EXTENDED if flags_str.include?('x')
+              flags
+            end
+
+            # Find RuboCop config file in starting directory or parent directories
+            # @param start_dir [String] directory to start searching from
+            # @return [String, nil] path to config file or nil if not found
+            def find_rubocop_config(start_dir = Dir.pwd)
+              current_dir = start_dir
+              config_names = ['.rubocop.yml', '.rubocop.yaml']
+
+              # Search up the directory tree
+              loop do
+                config_names.each do |name|
+                  config_path = File.join(current_dir, name)
+                  return config_path if File.exist?(config_path)
+                end
+
+                parent_dir = File.dirname(current_dir)
+                break if parent_dir == current_dir # Reached root
+
+                current_dir = parent_dir
+              end
+
+              nil
+            end
+
+            # Check if example should be skipped based on skip patterns
+            # @param example_name [String] name of the example
+            # @return [Boolean] true if should skip
+            def should_skip?(example_name)
+              @skip_patterns.any? { |pattern| example_name.match?(pattern) }
+            end
+
+            # Clean code by removing output indicators and extra whitespace
+            # Mirrors the logic from ExampleSyntax validator
+            # @param code [String] raw code from @example tag
+            # @return [String] cleaned code with preserved trailing newline
+            def clean_code(code)
+              return '' if code.nil? || code.empty?
+
+              # Strip output indicators (#=>) and everything after it
+              code_lines = code.split("\n").map do |line|
+                line.sub(/\s*#\s*=>.*$/, '')
+              end
+
+              # Join lines and add single trailing newline for RuboCop
+              cleaned = code_lines.join("\n").strip
+              cleaned.empty? ? '' : "#{cleaned}\n"
+            end
+
+            # Run RuboCop on code and parse JSON output
+            # @param code [String] Ruby code snippet to analyze with RuboCop
+            # @param file_path [String] path to the file being linted (for config discovery)
+            # @return [Array<Hash>] array of offense hashes
+            def run_rubocop(code, file_path: nil)
+              # Determine working directory from file path
+              work_dir = file_path ? File.dirname(file_path) : Dir.pwd
+
+              # Build RuboCop command
+              cmd = ['rubocop', '--format', 'json', '--stdin', 'example.rb']
+
+              # Add config file if it exists in the file's directory
+              config_file = find_rubocop_config(work_dir)
+              cmd += ['--config', config_file] if config_file
+
+              # Add disabled cops (comma-separated)
+              unless @disabled_cops.empty?
+                cmd += ['--except', @disabled_cops.join(',')]
+              end
+
+              stdout, = Open3.capture3(*cmd, stdin_data: code, chdir: work_dir)
+
+              # RuboCop returns non-zero exit status when offenses are found
+              # We only care about actual errors (not offense findings)
+              return [] if stdout.empty?
+
+              parse_rubocop_output(stdout)
+            rescue Errno::ENOENT
+              warn '[YARD::Lint] ExampleStyle: rubocop command not found' if ENV['DEBUG']
+              []
+            end
+
+            # Run StandardRB on code and parse JSON output
+            # @param code [String] Ruby code snippet to analyze with StandardRB
+            # @param file_path [String] path to the file being linted (for config discovery)
+            # @return [Array<Hash>] array of offense hashes
+            def run_standard(code, file_path: nil)
+              # Determine working directory from file path
+              work_dir = file_path ? File.dirname(file_path) : Dir.pwd
+
+              # StandardRB doesn't support --except for individual cops
+              # Users must configure exclusions in .standard.yml
+              cmd = ['standardrb', '--format', 'json', '--stdin', 'example.rb']
+
+              stdout, = Open3.capture3(*cmd, stdin_data: code, chdir: work_dir)
+
+              # StandardRB returns non-zero exit status when offenses are found
+              return [] if stdout.empty?
+
+              parse_rubocop_output(stdout) # StandardRB uses RuboCop's JSON format
+            rescue Errno::ENOENT
+              warn '[YARD::Lint] ExampleStyle: standardrb command not found' if ENV['DEBUG']
+              []
+            end
+
+            # Parse RuboCop/StandardRB JSON output
+            # @param json_output [String] JSON output from linter
+            # @return [Array<Hash>] array of offense hashes
+            def parse_rubocop_output(json_output)
+              result = JSON.parse(json_output)
+
+              # RuboCop JSON format: { "files": [ { "offenses": [...] } ] }
+              files = result['files'] || []
+              return [] if files.empty?
+
+              file = files.first
+              offenses = file['offenses'] || []
+
+              offenses.map do |offense|
+                {
+                  cop_name: offense['cop_name'],
+                  message: offense['message'],
+                  line: offense['location']['line'],
+                  column: offense['location']['column'],
+                  severity: offense['severity']
+                }
+              end
+            rescue JSON::ParserError => e
+              warn "[YARD::Lint] ExampleStyle: Failed to parse linter output: #{e.message}" if ENV['DEBUG']
+              []
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleStyle
+          # Validator to check code style in @example tags using RuboCop/StandardRB
+          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 code style in @example tags using RuboCop or StandardRB.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              return unless object.has_tag?(:example)
+
+              # Get or initialize runner (memoized for performance)
+              return unless runner
+
+              # Process each example
+              example_tags = object.tags(:example)
+
+              example_tags.each_with_index do |example, index|
+                code = example.text
+                next if code.nil? || code.empty?
+
+                example_name = example.name || "Example #{index + 1}"
+
+                # Run linter (pass file path for context/config discovery)
+                offenses = runner.run(code, example_name, file_path: object.file)
+
+                # Output each offense
+                offenses.each do |offense|
+                  collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                  collector.puts 'style_offense'
+                  collector.puts example_name
+                  collector.puts offense[:cop_name]
+                  collector.puts offense[:message]
+                end
+              end
+            end
+
+            private
+
+            # Memoized runner instance
+            # @return [RubocopRunner, nil] runner instance or nil if no linter available
+            def runner
+              return @runner if defined?(@runner)
+
+              # Detect linter
+              linter_type = config_or_default('Linter')
+              detected_linter = LinterDetector.detect(linter_type)
+
+              # Gracefully skip if no linter available
+              if detected_linter == :none
+                warn_once_about_missing_linter if ENV['DEBUG']
+                @runner = nil
+                return nil
+              end
+
+              # Initialize and memoize runner
+              disabled_cops = config_or_default('DisabledCops')
+              skip_patterns = config_or_default('SkipPatterns')
+              @runner = RubocopRunner.new(
+                linter: detected_linter,
+                disabled_cops: disabled_cops,
+                skip_patterns: skip_patterns
+              )
+            end
+
+            # Warn once about missing linter (class-level tracking)
+            def warn_once_about_missing_linter
+              return if self.class.instance_variable_get(:@warned_about_linter)
+
+              warn '[YARD::Lint] ExampleStyle validator enabled but no linter (RuboCop/StandardRB) found. Skipping.'
+              self.class.instance_variable_set(:@warned_about_linter, true)
+            end
+          end
+        end
+      end
+    end
+  end
+end