yard-lint 1.0.0 → 1.2.0

data/lib/yard/lint/runner.rb

@@ -21,7 +21,7 @@ module Yard
       def run
         raw_results = run_validators
         parsed_results = parse_results(raw_results)
-        build_result(parsed_results)
+        build_result(parsed_results, @selection)
       end
 
       private
@@ -116,9 +116,10 @@ module Yard
 
       # Build final result object
       # @param results [Array<Results::Base>] array of validator result objects
+      # @param files [Array<String>] array of files that were analyzed
       # @return [Results::Aggregate] aggregate result object
-      def build_result(results)
-        Results::Aggregate.new(results, config)
+      def build_result(results, files)
+        Results::Aggregate.new(results, config, files)
       end
     end
   end

data/lib/yard/lint/stats_calculator.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Calculates documentation coverage statistics
+    # Runs YARD queries to count documented vs undocumented objects
+    class StatsCalculator
+      attr_reader :config, :files
+
+      # @param config [Yard::Lint::Config] configuration object
+      # @param files [Array<String>] files to analyze
+      def initialize(config, files)
+        @config = config
+        @files = Array(files).compact
+      end
+
+      # Calculate documentation coverage statistics
+      # @return [Hash] statistics with :total, :documented, :coverage keys
+      def calculate
+        return default_stats if files.empty?
+
+        raw_stats = run_yard_stats_query
+        return default_stats if raw_stats.empty?
+
+        parsed_stats = parse_stats_output(raw_stats)
+        filtered_stats = apply_exclusions(parsed_stats)
+
+        calculate_coverage_percentage(filtered_stats)
+      end
+
+      private
+
+      # Default stats for empty file lists
+      # @return [Hash]
+      def default_stats
+        { total: 0, documented: 0, coverage: 100.0 }
+      end
+
+      # Run YARD query to get object documentation status
+      # @return [String] YARD query output
+      def run_yard_stats_query
+        # Create temp file with file list
+        Tempfile.create(['yard_stats', '.txt']) do |f|
+          files.each { |file| f.puts(Shellwords.escape(file)) }
+          f.flush
+
+          query = build_stats_query
+
+          # Use temp directory for YARD database (auto-cleanup)
+          Dir.mktmpdir("yard_stats_#{Process.pid}_") do |temp_dir|
+            cmd = build_yard_command(f.path, query, temp_dir)
+
+            stdout, _stderr, status = Open3.capture3(cmd)
+
+            # Return empty string if YARD command fails
+            return '' unless status.exitstatus.zero?
+
+            stdout
+          end
+        end
+      end
+
+      # Build the YARD query for stats collection
+      # @return [String] YARD query string
+      def build_stats_query
+        <<~QUERY.chomp
+          type = object.type.to_s; state = object.docstring.all.empty? ? "undoc" : "doc"; puts "\#{type}:\#{state}"
+        QUERY
+      end
+
+      # Build complete YARD command
+      # @param file_list_path [String] path to file with list of files
+      # @param query [String] YARD query to execute
+      # @param temp_dir [String] temporary directory for YARD database
+      # @return [String] complete command string
+      def build_yard_command(file_list_path, query, temp_dir)
+        <<~CMD.tr("\n", ' ').strip
+          cat #{Shellwords.escape(file_list_path)} | xargs yard list
+          --charset utf-8
+          --markup markdown
+          --no-progress
+          --query #{Shellwords.escape(query)}
+          -q
+          -b #{Shellwords.escape(temp_dir)}
+        CMD
+      end
+
+      # Parse YARD stats output
+      # Format: "type:state" (e.g., "method:doc", "class:undoc")
+      # @param output [String] YARD command output
+      # @return [Hash] counts by type and state
+      def parse_stats_output(output)
+        stats = Hash.new { |h, k| h[k] = { documented: 0, undocumented: 0 } }
+
+        output.each_line do |line|
+          line.strip!
+          next if line.empty?
+
+          type, state = line.split(':', 2)
+          next unless type && state
+
+          if state == 'doc'
+            stats[type][:documented] += 1
+          elsif state == 'undoc'
+            stats[type][:undocumented] += 1
+          end
+        end
+
+        stats
+      end
+
+      # Apply validator exclusions to stats
+      # Respects ExcludedMethods and other validator-specific exclusions
+      # @param stats [Hash] parsed stats
+      # @return [Hash] filtered stats
+      def apply_exclusions(stats)
+        # Get excluded methods from UndocumentedObjects validator config
+        excluded_methods = config.validator_config('Documentation/UndocumentedObjects', 'ExcludedMethods') || []
+
+        return stats if excluded_methods.empty?
+
+        # For now, we can't easily filter out specific methods without re-parsing
+        # This would require running YARD query with method names
+        # TODO: Implement precise method-level filtering if needed
+
+        stats
+      end
+
+      # Calculate coverage percentage from stats
+      # @param stats [Hash] filtered stats by type
+      # @return [Hash] final coverage statistics
+      def calculate_coverage_percentage(stats)
+        total_documented = 0
+        total_undocumented = 0
+
+        stats.each_value do |counts|
+          total_documented += counts[:documented]
+          total_undocumented += counts[:undocumented]
+        end
+
+        total_objects = total_documented + total_undocumented
+
+        coverage = if total_objects.zero?
+                     100.0
+                   else
+                     (total_documented.to_f / total_objects * 100)
+                   end
+
+        {
+          total: total_objects,
+          documented: total_documented,
+          coverage: coverage
+        }
+      end
+    end
+  end
+end

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

@@ -143,6 +143,42 @@ module Yard
         def shell(cmd)
           self.class.command_cache.execute(cmd)
         end
+
+        # Retrieves configuration value with fallback to default
+        # Automatically determines the validator name from the class namespace
+        #
+        # @param key [String] the configuration key to retrieve
+        # @return [Object] the configured value or default value from the validator's Config.defaults
+        # @note The validator name is automatically extracted from the class namespace.
+        #   For example, Yard::Lint::Validators::Tags::RedundantParamDescription::Validator
+        #   becomes 'Tags/RedundantParamDescription'
+        # @example Usage in a validator (e.g., Tags::RedundantParamDescription)
+        #   def config_articles
+        #     config_or_default('Articles')
+        #   end
+        def config_or_default(key)
+          validator_name = self.class.name&.split('::')&.then do |parts|
+            idx = parts.index('Validators')
+            next nil unless idx && parts[idx + 1] && parts[idx + 2]
+
+            "#{parts[idx + 1]}/#{parts[idx + 2]}"
+          end
+
+          # Get the validator module's Config class
+          validator_config_class = begin
+            # Get parent module (e.g., Yard::Lint::Validators::Tags::RedundantParamDescription)
+            parent_module = self.class.name.split('::')[0..-2].join('::')
+            Object.const_get("#{parent_module}::Config")
+          rescue NameError
+            nil
+          end
+
+          defaults = validator_config_class&.defaults || {}
+
+          return defaults[key] unless validator_name
+
+          config.validator_config(validator_name, key) || defaults[key]
+        end
       end
     end
   end

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

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

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MarkdownSyntax
+          # Builds human-readable messages for MarkdownSyntax violations
+          class MessagesBuilder
+            # Maps markdown syntax error types to human-readable descriptions
+            ERROR_DESCRIPTIONS = {
+              'unclosed_backtick' => 'Unclosed backtick in documentation',
+              'unclosed_code_block' => 'Unclosed code block (```) in documentation',
+              'unclosed_bold' => 'Unclosed bold formatting (**) in documentation',
+              'invalid_list_marker' => 'Invalid list marker (use - or * instead)'
+            }.freeze
+
+            class << self
+              # Formats a violation message
+              # @param offense [Hash] the offense details
+              # @return [String] formatted message
+              def call(offense)
+                object_name = offense[:object_name]
+                errors = offense[:errors]
+
+                error_messages = errors.map do |error|
+                  if error.start_with?('invalid_list_marker:')
+                    line_num = error.split(':').last
+                    "#{ERROR_DESCRIPTIONS['invalid_list_marker']} at line #{line_num}"
+                  else
+                    ERROR_DESCRIPTIONS[error] || error
+                  end
+                end
+
+                "Markdown syntax errors in '#{object_name}': " \
+                  "#{error_messages.join(', ')}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MarkdownSyntax
+          # Parses YARD output for markdown syntax 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 error types
+                  i += 1
+                  next unless i < lines.size
+
+                  errors = lines[i].split('|')
+
+                  violations << {
+                    location: file_path,
+                    line: line_number,
+                    object_name: object_name,
+                    errors: errors
+                  }
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MarkdownSyntax
+          # Validates markdown syntax in documentation
+          class Validator < Validators::Base
+            # YARD query to extract docstrings and check for markdown errors
+            # @return [String] YARD Ruby query code
+            def query
+              <<~QUERY.strip
+                'docstring_text = object.docstring.to_s; unless docstring_text.empty?; errors = []; backtick_count = docstring_text.scan(/\\x60/).count; errors << "unclosed_backtick" if backtick_count.odd?; code_block_count = docstring_text.scan(/^```/).count; errors << "unclosed_code_block" if code_block_count.odd?; non_code_text = docstring_text.gsub(/\\x60[^\\x60]*\\x60/, ""); bold_count = non_code_text.scan(/\\*\\*/).count; errors << "unclosed_bold" if bold_count.odd?; lines = docstring_text.lines; lines.each_with_index do |line, line_idx|; stripped = line.strip; errors << "invalid_list_marker:" + (line_idx + 1).to_s if stripped =~ /^[•·]/; end; unless errors.empty?; puts object.file + ":" + object.line.to_s + ": " + object.title; puts errors.join("|"); end; end; false'
+              QUERY
+            end
+
+            # Builds and executes the YARD command to detect markdown syntax errors
+            # @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/markdown_syntax.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # MarkdownSyntax validator
+        #
+        # Validates markdown syntax in documentation comments. This validator checks
+        # for common markdown errors and formatting issues in YARD documentation
+        # strings. This validator is enabled by default.
+        #
+        # @example Bad - Invalid markdown syntax
+        #   # This is [broken markdown
+        #   # Another line with `unclosed code
+        #   def process
+        #   end
+        #
+        # @example Good - Valid markdown syntax
+        #   # This is [valid markdown](https://example.com)
+        #   # Another line with `closed code`
+        #   def process
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/MarkdownSyntax:
+        #       Enabled: false
+        #
+        module MarkdownSyntax
+        end
+      end
+    end
+  end
+end

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

@@ -4,7 +4,32 @@ module Yard
   module Lint
     module Validators
       module Documentation
-        # UndocumentedBooleanMethods validator module
+        # UndocumentedBooleanMethods validator
+        #
+        # Ensures that boolean methods (methods ending with `?`) have an explicit
+        # `@return [Boolean]` tag. Boolean methods should clearly document that they
+        # return true or false values. This validator is enabled by default.
+        #
+        # @example Bad - Missing @return tag on boolean method
+        #   # Checks if the user is active
+        #   def active?
+        #     @active
+        #   end
+        #
+        # @example Good - Boolean return documented
+        #   # Checks if the user is active
+        #   # @return [Boolean] true if the user is active
+        #   def active?
+        #     @active
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/UndocumentedBooleanMethods:
+        #       Enabled: false
+        #
         module UndocumentedBooleanMethods
         end
       end

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

@@ -4,7 +4,32 @@ module Yard
   module Lint
     module Validators
       module Documentation
-        # UndocumentedMethodArguments validator module
+        # UndocumentedMethodArguments validator
+        #
+        # Ensures that all method parameters are documented with `@param` tags.
+        # This validator checks that every parameter in a method signature has
+        # a corresponding `@param` documentation tag. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Missing @param tags
+        #   # Does something with data
+        #   def process(name, options)
+        #   end
+        #
+        # @example Good - All parameters documented
+        #   # Does something with data
+        #   # @param name [String] the name to process
+        #   # @param options [Hash] configuration options
+        #   def process(name, options)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/UndocumentedMethodArguments:
+        #       Enabled: false
+        #
         module UndocumentedMethodArguments
         end
       end

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

@@ -4,8 +4,137 @@ module Yard
   module Lint
     module Validators
       module Documentation
-        # UndocumentedObjects validator module
-        # This validator checks for missing documentation on objects
+        # UndocumentedObjects validator
+        #
+        # Checks for missing documentation on classes, modules, and methods.
+        # This validator supports flexible method exclusions through the `ExcludedMethods`
+        # configuration option.
+        #
+        # ## Pattern Types
+        #
+        # The `ExcludedMethods` feature supports three pattern types for maximum flexibility:
+        #
+        # ### 1. Exact Name Matching
+        #
+        # Excludes methods with the specified name, regardless of arity:
+        #
+        #     ExcludedMethods:
+        #       - 'to_s'           # Excludes ALL to_s methods regardless of parameters
+        #       - 'inspect'        # Excludes ALL inspect methods
+        #
+        # Note: Exact name matching excludes the method with **any arity**. If you need
+        # arity-specific exclusions, use arity notation instead.
+        #
+        # ### 2. Arity Notation (method_name/N)
+        #
+        # Excludes methods with specific parameter counts:
+        #
+        #     ExcludedMethods:
+        #       - 'initialize/0'   # Only excludes initialize with NO parameters (default)
+        #       - 'call/1'         # Only excludes call methods with exactly 1 parameter
+        #       - 'initialize/2'   # Only excludes initialize with exactly 2 parameters
+        #
+        # Note: Arity counts total parameters (required + optional) excluding splat (*)
+        # and block (&) parameters.
+        #
+        # ### 3. Regex Patterns
+        #
+        # Excludes methods matching a regular expression:
+        #
+        #     ExcludedMethods:
+        #       - '/^_/'           # Excludes all methods starting with underscore (private convention)
+        #       - '/^test_/'       # Excludes all test methods
+        #       - '/_(helper|util)$/' # Excludes methods ending with _helper or _util
+        #
+        # ## Configuration Examples
+        #
+        # ### Minimal setup - Only exclude parameter-less initialize
+        #
+        #     Documentation/UndocumentedObjects:
+        #       ExcludedMethods:
+        #         - 'initialize/0'
+        #
+        # ### Common Rails/Ruby patterns
+        #
+        #     Documentation/UndocumentedObjects:
+        #       ExcludedMethods:
+        #         - 'initialize/0'       # Parameter-less constructors
+        #         - '/^_/'               # Private methods (by convention)
+        #         - 'to_s'               # String conversion
+        #         - 'inspect'            # Object inspection
+        #         - 'hash'               # Hash code generation
+        #         - 'eql?'               # Equality comparison
+        #         - '=='                 # Binary equality operator
+        #         - '<=>'                # Spaceship operator (comparison)
+        #         - '+'                  # Addition operator
+        #         - '-'                  # Subtraction operator
+        #         - '+@'                 # Unary plus operator
+        #         - '-@'                 # Unary minus operator
+        #
+        # ### Test framework exclusions
+        #
+        #     Documentation/UndocumentedObjects:
+        #       ExcludedMethods:
+        #         - '/^test_/'           # Minitest methods
+        #         - '/^should_/'         # Shoulda methods
+        #         - 'setup/0'            # Setup with no params
+        #         - 'teardown/0'         # Teardown with no params
+        #
+        # ## Pattern Validation & Edge Cases
+        #
+        # The `ExcludedMethods` feature includes robust validation and error handling:
+        #
+        # **Automatic Pattern Sanitization:**
+        # - **Nil values** are automatically removed
+        # - **Empty strings** and whitespace-only patterns are filtered out
+        # - **Whitespace trimming** is applied to all patterns
+        # - **Empty regex patterns** (`//`) are rejected (would match everything)
+        # - **Non-array values** are automatically converted to arrays
+        #
+        # **Invalid Pattern Handling:**
+        # - **Invalid regex patterns** (e.g., `/[/`, `/(unclosed`) are silently skipped without crashing
+        # - **Invalid arity notation** (e.g., `method/abc`, `method/`) is silently skipped
+        # - **Pattern matching is case-sensitive** for both exact names and regex
+        #
+        # **Operator Method Support:**
+        # YARD-Lint fully supports Ruby operator methods including:
+        # - Binary operators: `+`, `-`, `*`, `/`, `%`, `**`, `==`, `!=`, `===`, `<`, `>`,
+        #   `<=`, `>=`, `<=>`, `&`, `|`, `^`, `<<`, `>>`
+        # - Unary operators: `+@`, `-@`, `!`, `~`
+        # - Other special methods: `[]`, `[]=`, `=~`
+        #
+        # **Pattern Matching Behavior:**
+        # - **Any match excludes**: If a method matches any pattern, it is excluded from validation
+        # - **Patterns are evaluated in order** as defined in the configuration
+        # - **Exact names have no arity restriction**: `'initialize'` excludes all initialize
+        #   methods, regardless of parameters
+        # - **Arity notation is strict**: `'initialize/0'` only excludes initialize with
+        #   exactly 0 parameters
+        #
+        # ## Troubleshooting
+        #
+        # ### Methods still showing as undocumented
+        #
+        # 1. Verify the method name matches exactly (case-sensitive)
+        # 2. Check if you're using arity notation - ensure the arity count is correct
+        # 3. For regex patterns, test your regex independently to ensure it matches
+        # 4. Remember: Arity counts `required + optional` parameters, **excluding**
+        #    splat (`*args`) and block (`&block`)
+        #
+        # ### Regex patterns not working
+        #
+        # 1. Ensure you're using `/pattern/` format with forward slashes
+        # 2. Test the regex in Ruby: `Regexp.new('your_pattern').match?('method_name')`
+        # 3. Escape special regex characters: `\.`, `\(`, `\)`, `\[`, `\]`, etc.
+        # 4. Invalid regex patterns are silently skipped - check for syntax errors
+        #
+        # ### Arity not matching
+        #
+        # 1. Count parameters correctly: `def method(a, b = 1)` has arity 2 (required + optional)
+        # 2. Splat parameters don't count: `def method(a, *rest)` has arity 1
+        # 3. Block parameters don't count: `def method(a, &block)` has arity 1
+        # 4. Keyword arguments count as individual parameters: `def method(a:, b:)` has arity 2
+        #
         module UndocumentedObjects
         end
       end

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

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