yard-lint 1.3.0 → 1.5.0

data/lib/yard/lint/todo_generator.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Generates .yard-lint-todo.yml file with exclusions for current violations
+    class TodoGenerator
+      # Default grouping threshold (15+ files triggers pattern grouping)
+      DEFAULT_EXCLUDE_LIMIT = 15
+
+      class << self
+        # Generate .yard-lint-todo.yml file with exclusions for current violations
+        # @param path [String] directory or file path containing Ruby files to analyze for violations
+        # @param config [Config] yard-lint configuration object with validator settings
+        # @param force [Boolean] whether to overwrite existing todo file if present
+        # @param exclude_limit [Integer] minimum files in directory before grouping into wildcard patterns
+        # @return [Hash] result with :message, :offense_count, :validator_count
+        def generate(path:, config:, force: false, exclude_limit: DEFAULT_EXCLUDE_LIMIT)
+          new(path: path, config: config, force: force, exclude_limit: exclude_limit).generate
+        end
+      end
+
+      # Initialize a new TodoGenerator instance
+      # @param path [String] directory or file path containing Ruby files to analyze
+      # @param config [Config] yard-lint configuration object
+      # @param force [Boolean] whether to overwrite existing todo file
+      # @param exclude_limit [Integer] minimum files before grouping into patterns
+      def initialize(path:, config:, force:, exclude_limit:)
+        @path = path
+        @config = config
+        @force = force
+        @exclude_limit = exclude_limit
+        @todo_path = File.join(Dir.pwd, '.yard-lint-todo.yml')
+        @config_path = File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
+      end
+
+      # Generate the .yard-lint-todo.yml file with exclusions for current violations
+      # @return [Hash] result hash with :message, :offense_count, :validator_count keys
+      def generate
+        # Step 1: Check if todo file exists
+        validate_todo_file_not_exists! unless @force
+
+        # Step 2: Run linting to collect violations
+        lint_result = run_linting
+
+        # Step 3: Handle clean codebase
+        return no_violations_result if lint_result[:violations_by_validator].empty?
+
+        # Step 4: Group violations by validator
+        violations_by_validator = group_violations_by_validator(lint_result)
+
+        # Step 5: Generate todo YAML content
+        todo_content = build_todo_yaml(violations_by_validator)
+
+        # Step 6: Write todo file
+        File.write(@todo_path, todo_content)
+
+        # Step 7: Update main config to inherit todo file
+        update_main_config
+
+        # Step 8: Build success message
+        build_success_result(violations_by_validator, lint_result[:total_offenses])
+      end
+
+      private
+
+      # Validate that the todo file doesn't already exist
+      # @return [void]
+      # @raise [Errors::TodoFileExistsError] if todo file exists and force is false
+      def validate_todo_file_not_exists!
+        return unless File.exist?(@todo_path)
+
+        raise Errors::TodoFileExistsError,
+          '.yard-lint-todo.yml already exists. Use --regenerate-todo to overwrite.'
+      end
+
+      # Run linting and collect violations per validator
+      # @return [Hash] hash with :violations_by_validator and :total_offenses keys
+      def run_linting
+        # Run each validator individually to track violations per validator
+        # This is more reliable than trying to infer validator from offense name
+        files = Yard::Lint.send(:expand_path, @path, @config)
+        runner = Runner.new(files, @config)
+
+        # Run validators and collect raw results
+        raw_results = runner.send(:run_validators)
+        result_builder = ResultBuilder.new(@config)
+
+        violations_by_validator = {}
+        total_offenses = 0
+
+        # Process each validator's results
+        ConfigLoader::ALL_VALIDATORS.each do |validator_name|
+          next unless @config.validator_enabled?(validator_name)
+
+          validator_result = result_builder.build(validator_name, raw_results)
+          next unless validator_result && validator_result.offenses.any?
+
+          # Extract file paths from offenses
+          file_paths = validator_result.offenses.map do |offense|
+            make_relative_path(offense[:location])
+          end.uniq.sort
+
+          violations_by_validator[validator_name] = file_paths
+          total_offenses += validator_result.count
+        end
+
+        { violations_by_validator: violations_by_validator, total_offenses: total_offenses }
+      end
+
+      # Build result hash for when no violations are found
+      # @return [Hash] result indicating clean codebase
+      def no_violations_result
+        {
+          message: "No offenses found. No .yard-lint-todo.yml needed.\nYour codebase is already compliant!",
+          offense_count: 0,
+          validator_count: 0
+        }
+      end
+
+      # Apply path grouping to each validator's file list
+      # @param lint_result [Hash] hash containing violations_by_validator data
+      # @return [Hash] hash of validator names to grouped file patterns
+      def group_violations_by_validator(lint_result)
+        # Apply path grouping to each validator's file list
+        lint_result[:violations_by_validator].transform_values do |files|
+          PathGrouper.group(files, limit: @exclude_limit)
+        end
+      end
+
+      # Convert absolute path to relative path from current directory
+      # @param path [String] absolute or relative file path
+      # @return [String] relative path from current directory
+      def make_relative_path(path)
+        pwd = Dir.pwd
+        path.start_with?(pwd) ? path.sub("#{pwd}/", '') : path
+      end
+
+      # Build YAML content for the todo file
+      # @param violations_by_validator [Hash] hash of validator names to file patterns
+      # @return [String] formatted YAML content
+      def build_todo_yaml(violations_by_validator)
+        lines = []
+
+        # Header
+        lines << "# This file was auto-generated by yard-lint --auto-gen-config on #{Time.now.utc.strftime('%Y-%m-%d %H:%M:%S UTC')}"
+        lines << '# It contains exclusions for all current violations to establish a baseline.'
+        lines << '#'
+        lines << '# To gradually fix violations:'
+        lines << '# 1. Remove files/patterns from the Exclude list below'
+        lines << '# 2. Run yard-lint to see the violations for those files'
+        lines << '# 3. Fix the violations'
+        lines << '# 4. Commit the changes'
+        lines << '#'
+        lines << '# To regenerate this file, run: yard-lint --regenerate-todo'
+        lines << ''
+
+        # Group validators by category
+        categories = group_by_category(violations_by_validator)
+
+        # Write each category
+        ConfigUpdater::CATEGORY_ORDER.each do |category|
+          validators = categories[category]
+          next unless validators&.any?
+
+          lines << ConfigUpdater::CATEGORY_COMMENTS[category] if ConfigUpdater::CATEGORY_COMMENTS[category]
+
+          validators.each do |validator_name, file_patterns|
+            lines << "#{validator_name}:"
+            lines << '  Exclude:'
+            file_patterns.each do |pattern|
+              lines << "    - '#{pattern}'"
+            end
+            lines << ''
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Group validators by their category (Documentation, Tags, etc.)
+      # @param violations_by_validator [Hash] hash of validator names to patterns
+      # @return [Hash] validators grouped by category
+      def group_by_category(violations_by_validator)
+        categories = Hash.new { |h, k| h[k] = {} }
+
+        violations_by_validator.each do |validator_name, patterns|
+          category = validator_name.split('/').first
+          categories[category][validator_name] = patterns
+        end
+
+        categories
+      end
+
+      # Update or create main config file to inherit from todo file
+      # @return [void]
+      def update_main_config
+        if File.exist?(@config_path)
+          update_existing_config
+        else
+          create_minimal_config
+        end
+      end
+
+      # Update existing config file to add inherit_from todo file
+      # @return [void]
+      def update_existing_config
+        config_yaml = YAML.load_file(@config_path) || {}
+        inherit_from = Array(config_yaml['inherit_from'] || [])
+
+        # Add todo file to inherit_from if not already present
+        unless inherit_from.include?('.yard-lint-todo.yml')
+          inherit_from.unshift('.yard-lint-todo.yml')
+          config_yaml['inherit_from'] = inherit_from
+
+          # Write updated config
+          File.write(@config_path, config_yaml.to_yaml)
+        end
+      end
+
+      # Create a minimal config file that inherits from todo file
+      # @return [void]
+      def create_minimal_config
+        content = <<~YAML
+          # YARD-Lint Configuration
+          # See https://github.com/mensfeld/yard-lint for documentation
+
+          inherit_from:
+            - .yard-lint-todo.yml
+        YAML
+
+        File.write(@config_path, content)
+      end
+
+      # Build success result hash with summary message
+      # @param violations_by_validator [Hash] hash of validator names to file patterns
+      # @param total_offenses [Integer] total number of offenses found
+      # @return [Hash] result with :message, :offense_count, :validator_count keys
+      def build_success_result(violations_by_validator, total_offenses)
+        lines = []
+        lines << 'Created .yard-lint-todo.yml'
+        lines << "Silenced #{total_offenses} offense(s) across #{violations_by_validator.size} validator(s):"
+
+        violations_by_validator.each do |validator_name, file_patterns|
+          lines << "  #{validator_name}: #{file_patterns.size} pattern(s)"
+        end
+
+        lines << ''
+        lines << 'Updated .yard-lint.yml to inherit from .yard-lint-todo.yml' if File.exist?(@config_path)
+        lines << ''
+        lines << 'Run yard-lint again to confirm - you should see no offenses.'
+        lines << 'To fix violations incrementally, remove entries from .yard-lint-todo.yml'
+
+        {
+          message: lines.join("\n"),
+          offense_count: total_offenses,
+          validator_count: violations_by_validator.size
+        }
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/base.rb

@@ -85,7 +85,7 @@ module Yard
         # @return [Object] the configured value or default value from the validator's Config.defaults
         # @example Usage in a validator (e.g., Tags::RedundantParamDescription)
         #   def config_articles
-        #     config_or_default('Articles')
+        #     config_or_default("Articles")
         #   end
         # @note The validator name is automatically extracted from the class namespace.
         #   For example, Yard::Lint::Validators::Tags::RedundantParamDescription::Validator

data/lib/yard/lint/validators/documentation/missing_return/config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MissingReturn
+          # Configuration for MissingReturn validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :missing_return
+            self.defaults = {
+              'Enabled' => false, # Disabled by default (opt-in validator)
+              'Severity' => 'warning',
+              'ExcludedMethods' => [
+                'initialize' # Exclude all initialize methods by default
+              ]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/missing_return/messages_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MissingReturn
+          # Builds messages for missing return tag offenses
+          class MessagesBuilder
+            class << self
+              # Build message for a method missing @return tag
+              # @param offense [Hash] offense data with :element key
+              # @return [String] formatted message
+              def call(offense)
+                "Missing @return tag for `#{offense[:element]}`"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MissingReturn
+          # Class used to extract details about methods missing @return tags from validator output
+          # @example Output format (skip-lint)
+          #   /path/to/file.rb:3: ClassName#method_name|2
+          #   /path/to/file.rb:10: ModuleName.class_method|0
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Regex used to parse validator output format
+            # Format: file.rb:LINE: ObjectName|ARITY
+            LINE_REGEX = /^(.+):(\d+): (.+?)\|(\d+)$/
+
+            # @param validator_output [String] raw validator results string
+            # @param config [Yard::Lint::Config, nil] configuration object (optional)
+            # @return [Array<Hash>] Array with methods missing @return tags
+            def call(validator_output, config: nil)
+              excluded_methods = config&.validator_config(
+                'Documentation/MissingReturn',
+                'ExcludedMethods'
+              ) || []
+
+              # Ensure excluded_methods is an Array
+              excluded_methods = Array(excluded_methods)
+
+              # Sanitize patterns: remove nil, empty, whitespace-only, and normalize
+              excluded_methods = sanitize_patterns(excluded_methods)
+
+              validator_output
+                .split("\n")
+                .map(&:strip)
+                .reject(&:empty?)
+                .filter_map do |line|
+                  match = line.match(LINE_REGEX)
+                  next unless match
+
+                  element = match[3]
+                  arity = match[4].to_i
+
+                  # Skip if method is in excluded list
+                  next if method_excluded?(element, arity, excluded_methods)
+
+                  {
+                    location: match[1],
+                    line: match[2].to_i,
+                    element: element
+                  }
+                end
+            end
+
+            private
+
+            # Checks if a method should be excluded based on ExcludedMethods config
+            # Supports: simple names, arity notation, and regex patterns
+            # @param element [String] the element name (e.g., "Class#method")
+            # @param arity [Integer] number of parameters (required + optional,
+            #   excluding splat and block)
+            # @param excluded_methods [Array<String>] list of exclusion patterns
+            # @return [Boolean] true if method should be excluded
+            def method_excluded?(element, arity, excluded_methods)
+              # Extract method name from element (e.g., "Foo::Bar#baz" -> "baz")
+              method_name = element.split(/[#.]/).last
+              return false unless method_name
+
+              excluded_methods.any? do |pattern|
+                case pattern
+                when %r{^/(.+)/$}
+                  # Regex pattern: '/^_/' matches methods starting with _
+                  match_regex_pattern(method_name, Regexp.last_match(1))
+                when %r{/\d+$}
+                  # Arity pattern: 'initialize/0' checks method name and parameter count
+                  match_arity_pattern(method_name, arity, pattern)
+                else
+                  # Simple name match: 'initialize'
+                  # Simple names match any arity (use arity notation for specific arity)
+                  method_name == pattern
+                end
+              end
+            end
+
+            # Sanitize exclusion patterns
+            # @param patterns [Array] raw patterns from config
+            # @return [Array<String>] cleaned and validated patterns
+            def sanitize_patterns(patterns)
+              patterns
+                .compact # Remove nil values
+                .map { |p| p.to_s.strip } # Convert to strings and trim whitespace
+                .reject(&:empty?) # Remove empty strings
+                .reject { |p| p == '//' } # Reject empty regex (matches everything)
+            end
+
+            # Match a regex pattern against method name with error handling
+            # @param method_name [String] the method name to match
+            # @param regex_pattern [String] the regex pattern (without delimiters)
+            # @return [Boolean] true if matches, false if invalid regex or no match
+            def match_regex_pattern(method_name, regex_pattern)
+              return false if regex_pattern.empty? # Empty regex would match everything
+
+              Regexp.new(regex_pattern).match?(method_name)
+            rescue RegexpError
+              # Invalid regex - skip this pattern
+              false
+            end
+
+            # Match an arity pattern like "initialize/0"
+            # @param method_name [String] the method name
+            # @param arity [Integer] number of parameters the method accepts
+            # @param pattern [String] the full pattern like "initialize/0"
+            # @return [Boolean] true if matches
+            def match_arity_pattern(method_name, arity, pattern)
+              pattern_name, pattern_arity_str = pattern.split('/')
+
+              # Validate arity is numeric
+              return false unless pattern_arity_str.match?(/^\d+$/)
+
+              pattern_arity = pattern_arity_str.to_i
+
+              method_name == pattern_name && arity == pattern_arity
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MissingReturn
+          # Result object for missing return tag validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'MissingReturnTag'
+
+            # Build human-readable message for missing return tag offense
+            # @param offense [Hash] offense data
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MissingReturn
+          # Runs a query that will pick all methods that do not have a @return tag documented
+          class Validator < Base
+            # Enable in-process execution for this validator
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Finds methods without @return tag.
+            # @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)
+              # Only check methods
+              return unless object.type == :method
+              # Skip aliases and implicit methods
+              return if object.is_alias?
+              return unless object.is_explicit?
+
+              # Check if @return tag is missing
+              return_tag = object.tag(:return)
+              return unless return_tag.nil?
+
+              # Calculate arity (exclude splat and block parameters)
+              arity = object.parameters.reject { |p| p[0].to_s.start_with?('*', '&') }.size
+
+              # Output method with arity for parser filtering
+              collector.puts "#{object.file}:#{object.line}: #{object.title}|#{arity}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # MissingReturn validator
+        #
+        # Ensures that all methods have an explicit `@return` tag documented.
+        # This validator helps maintain consistent API documentation by catching
+        # methods that are missing return value documentation. This validator is
+        # disabled by default and must be explicitly enabled in configuration.
+        #
+        # @example Bad - Missing @return tag
+        #   # Calculates the total price
+        #   def calculate_total
+        #     @items.sum(&:price)
+        #   end
+        #
+        # @example Good - Return value documented
+        #   # Calculates the total price
+        #   # @return [Float] the total price of all items
+        #   def calculate_total
+        #     @items.sum(&:price)
+        #   end
+        #
+        # ## Configuration
+        #
+        # This validator is disabled by default. To enable it:
+        #
+        #     Documentation/MissingReturn:
+        #       Enabled: true
+        #       Severity: warning
+        #       ExcludedMethods:
+        #         - initialize
+        #         - '/^_/'  # Exclude private methods starting with underscore
+        #
+        # ### ExcludedMethods
+        #
+        # Supports three pattern types:
+        # - Simple name: 'initialize' - matches all methods with that name
+        # - Arity notation: 'initialize/0' - matches only methods with specific parameter count
+        # - Regex pattern: '/^_/' - matches methods using regular expressions
+        module MissingReturn
+        end
+      end
+    end
+  end
+end

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

@@ -7,7 +7,7 @@ module Yard
       module Documentation
         module UndocumentedBooleanMethods
           # Class used to extract details about undocumented boolean methods
-          # @example
+          # @example Output format (skip-lint)
           #   Platform::Analysis::Authors#valid?
           class Parser < Parsers::Base
             # Regex to extract location and method name from yard list output

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

@@ -6,7 +6,7 @@ module Yard
       module Documentation
         module UndocumentedMethodArguments
           # Class used to extract details about methods with undocumented arguments
-          # @example
+          # @example Output format (skip-lint)
           #   /path/to/file.rb:10: Platform::Analysis::Authors#initialize
           class Parser < Parsers::Base
             # Regex to extract file, line, and method name from yard list output

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

@@ -21,6 +21,9 @@ module Yard
               # Skip aliases and implicit methods
               return if object.is_alias?
               return unless object.is_explicit?
+              # Skip attribute methods (@!attribute directive) — their setter parameter
+              # doesn't need explicit @param documentation, matching attr_accessor behavior
+              return if object.is_attribute?
 
               # Check if parameters count exceeds @param tags count
               param_count = object.parameters.size

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

@@ -6,7 +6,7 @@ module Yard
       module Documentation
         module UndocumentedObjects
           # Class used to extract details about undocumented objects from raw yard list output
-          # @example
+          # @example Output format (skip-lint)
           #   /path/to/file.rb:3: UndocumentedClass
           #   /path/to/file.rb:4: UndocumentedClass#method_one|2
           class Parser < ::Yard::Lint::Parsers::Base

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

@@ -47,6 +47,12 @@ module Yard
                 if type_string.start_with?('{')
                   # {K => V} -> Hash{K => V}
                   "Hash#{type_string}"
+                elsif type_string.start_with?('<')
+                  # <String> -> Array<String>
+                  "Array#{type_string}"
+                elsif type_string.start_with?('(')
+                  # (String, Integer) -> Array(String, Integer)
+                  "Array#{type_string}"
                 else
                   # Hash<K, V> -> Hash{K => V}
                   type_string.gsub(/Hash<(.+?)>/) do
@@ -61,8 +67,8 @@ module Yard
               # @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/, '')
+                # Hash{K => V} -> {K => V} or Array<String> -> <String> or Array(S, I) -> (S, I)
+                type_string.sub(/^(Hash|Array)/, '')
               end
             end
           end