yard-lint 0.2.0

data/lib/yard/lint/parsers/two_line_base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Parsers
+      # Base class for all two line warnings parsers
+      class TwoLineBase < Base
+        # @param yard_stats [String] raw yard stats results string
+        # @return [Array<Hash>] array with all warnings informations from yard stats analysis
+        def call(yard_stats)
+          # Not all the lines from the yard_stats output are valuable, that's why we filter
+          # them out, preprocess and leave only those against which we should match
+          rows = classify(yard_stats.split("\n"))
+
+          rows.map do |warning|
+            {
+              name: self.class.to_s.split('::').last,
+              message: match(warning[0], :message).last,
+              location: match(warning[1], :location).last,
+              line: match(warning[1], :line).last.to_i
+            }
+          end
+        end
+
+        private
+
+        # @param rows [Array<String>] array with lines of output from yard stats
+        # @return [Array<Array<String>>] Array with always two elements - row that was
+        #   classified and the next one because yard returns valuable chunks of informations
+        #   in two lines that are one after another
+        def classify(rows)
+          buffor = []
+
+          rows.each.with_index do |row, index|
+            next unless row.match? self.class.regexps[:general]
+
+            buffor << [rows[index].to_s, rows[index + 1].to_s]
+          end
+
+          buffor
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/result_builder.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Builds result objects from raw validator output
+    # Handles standard validators, multi-parser validators, and composite validators
+    class ResultBuilder
+      attr_reader :config
+
+      # @param config [Config] configuration object
+      def initialize(config)
+        @config = config
+      end
+
+      # Build result for a single validator
+      # Uses convention-based discovery to handle all validator types uniformly
+      # @param validator_name [String] validator name (e.g., 'Tags/Order')
+      # @param raw [Hash] raw results from all validators
+      # @return [Results::Base, nil] result object or nil if no offenses
+      def build(validator_name, raw)
+        validator_module = ConfigLoader.validator_module(validator_name)
+        validator_cfg = ConfigLoader.validator_config(validator_name)
+        return nil unless validator_module && validator_cfg
+
+        # Skip if this validator is a child of a composite
+        return nil if composite_child?(validator_name)
+
+        # Handle composite validators (those that combine multiple validators)
+        unless validator_cfg.combines_with.empty?
+          return build_composite_result(validator_module, validator_cfg, raw)
+        end
+
+        # Handle standard validators (single or multi-parser)
+        build_standard_result(validator_module, validator_cfg, raw)
+      end
+
+      private
+
+      # Check if a validator is a child of a composite validator
+      # @param validator_name [String] validator name to check
+      # @return [Boolean] true if this is a composite child
+      def composite_child?(validator_name)
+        ConfigLoader::ALL_VALIDATORS.any? do |parent_name|
+          parent_cfg = ConfigLoader.validator_config(parent_name)
+          next unless parent_cfg
+
+          parent_cfg.combines_with.include?(validator_name)
+        end
+      end
+
+      # Build result for a composite validator (combines multiple validators)
+      # @param validator_module [Module] validator namespace module
+      # @param validator_cfg [Class] validator config class
+      # @param raw [Hash] raw results
+      # @return [Results::Base, nil] composite result or nil
+      def build_composite_result(validator_module, validator_cfg, raw)
+        # Collect all child validators (modules + configs)
+        children = validator_cfg.combines_with.filter_map do |child_name|
+          child_mod = ConfigLoader.validator_module(child_name)
+          child_cfg = ConfigLoader.validator_config(child_name)
+          [child_mod, child_cfg] if child_mod && child_cfg
+        end
+
+        # All validators (parent + children)
+        all_validators = [[validator_module, validator_cfg]] + children
+
+        # Parse output from all validators
+        combined = all_validators.flat_map do |mod, cfg|
+          parse_validator_output(mod, cfg, raw)
+        end
+
+        return nil if combined.empty?
+
+        validator_module::Result.new(combined, config)
+      end
+
+      # Build result for a standard validator (single or multi-parser)
+      # Auto-detects multi-parser validators by discovering parser classes
+      # @param validator_module [Module] validator namespace module
+      # @param validator_cfg [Class] validator config class
+      # @param raw [Hash] raw results
+      # @return [Results::Base, nil] result or nil
+      def build_standard_result(validator_module, validator_cfg, raw)
+        return nil unless raw[validator_cfg.id]
+
+        stdout = raw.dig(validator_cfg.id, :stdout)
+        return nil unless stdout
+
+        # Discover all parser classes in the validator module
+        parsers = discover_parsers(validator_module)
+        return nil if parsers.empty?
+
+        # Parse output with all parsers (single or multiple)
+        parsed = parsers.flat_map { |parser| parser.new.call(stdout) }
+        return nil if parsed.nil? || parsed.empty?
+
+        validator_module::Result.new(parsed, config)
+      end
+
+      # Parse output from a validator module
+      # @param validator_module [Module] validator namespace module
+      # @param validator_cfg [Class] validator config class
+      # @param raw [Hash] raw results
+      # @return [Array<Hash>] parsed offenses
+      def parse_validator_output(validator_module, validator_cfg, raw)
+        return [] unless raw[validator_cfg.id]
+
+        stdout = raw.dig(validator_cfg.id, :stdout)
+        return [] unless stdout
+
+        parsers = discover_parsers(validator_module)
+        parsers.flat_map { |parser| parser.new.call(stdout) }
+      end
+
+      # Auto-discover parser classes in a validator module
+      # Finds all classes that inherit from Parsers::Base
+      # @param validator_module [Module] validator module to search
+      # @return [Array<Class>] array of parser classes
+      def discover_parsers(validator_module)
+        validator_module.constants
+                        .map { |const_name| validator_module.const_get(const_name) }
+                        .select { |const| const.is_a?(Class) }
+                        .select { |klass| klass < Parsers::Base }
+                        .reject do |klass|
+          [validator_module::Validator, validator_module::Result].include?(klass)
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/results/aggregate.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Result objects for validators
+    module Results
+      # Aggregates multiple validator results into a single result object
+      class Aggregate
+        # Error severity level constant
+        SEVERITY_ERROR = 'error'
+        # Warning severity level constant
+        SEVERITY_WARNING = 'warning'
+        # Convention severity level constant
+        SEVERITY_CONVENTION = 'convention'
+
+        attr_reader :config
+
+        # Initialize aggregate result with array of validator results
+        # @param results [Array<Results::Base>] array of validator result objects
+        # @param config [Config, nil] configuration object
+        def initialize(results, config = nil)
+          @results = Array(results)
+          @config = config
+        end
+
+        # Get all offenses from all validators
+        # @return [Array<Hash>] flattened array of all offenses
+        def offenses
+          @results.flat_map(&:offenses)
+        end
+
+        # Total number of offenses
+        # @return [Integer] offense count
+        def count
+          offenses.count
+        end
+
+        # Check if there are no offenses
+        # @return [Boolean] true if no offenses found
+        def clean?
+          offenses.empty?
+        end
+
+        # Get offense statistics by severity
+        # @return [Hash] hash with severity counts (using symbol keys)
+        def statistics
+          stats = {
+            error: 0,
+            warning: 0,
+            convention: 0,
+            total: 0
+          }
+
+          offenses.each do |offense|
+            severity = offense[:severity].to_sym
+            stats[severity] += 1 if stats.key?(severity)
+            stats[:total] += 1
+          end
+
+          stats
+        end
+
+        # Determine exit code based on configured fail_on_severity
+        # Uses the config object stored during initialization
+        # @return [Integer] 0 for success, 1 for failure
+        def exit_code
+          return 0 if offenses.empty?
+          return 0 unless @config # No config means don't fail
+
+          fail_on = @config.fail_on_severity
+
+          case fail_on
+          when SEVERITY_ERROR
+            statistics[:error].positive? ? 1 : 0
+          when SEVERITY_WARNING
+            (statistics[:error] + statistics[:warning]).positive? ? 1 : 0
+          when SEVERITY_CONVENTION
+            offenses.any? ? 1 : 0
+          else
+            0
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Results
+      # Base class for validator-specific result objects
+      # Each validator should subclass this and set class attributes
+      #
+      # @example Creating a validator result class
+      #   class MyValidator::Result < Results::Base
+      #     self.default_severity = 'warning'
+      #     self.offense_type = 'method'
+      #     self.offense_name = 'MyOffense'
+      #
+      #     def build_message(offense)
+      #       "Found issue in #{offense[:location]}"
+      #     end
+      #   end
+      class Base
+        class << self
+          # Default severity level for this validator's offenses
+          # @return [String] 'error', 'warning', or 'convention'
+          attr_writer :default_severity
+
+          # Get the default severity level for this validator
+          # @return [String] 'error', 'warning', or 'convention'
+          def default_severity
+            @default_severity ||
+              (superclass.respond_to?(:default_severity) ? superclass.default_severity : nil)
+          end
+
+          # Type of offense for display purposes
+          # @return [String] 'line' or 'method'
+          attr_writer :offense_type
+
+          # Get the offense type for this validator
+          # @return [String] 'line' or 'method'
+          def offense_type
+            @offense_type ||
+              (superclass.respond_to?(:offense_type) ? superclass.offense_type : nil)
+          end
+
+          # Name of the offense for identification
+          # @return [String] offense name
+          attr_writer :offense_name
+
+          # Get the offense name for this validator
+          # @return [String] offense name
+          def offense_name
+            @offense_name ||
+              (superclass.respond_to?(:offense_name) ? superclass.offense_name : nil)
+          end
+        end
+
+        # Set default values for base class
+        self.offense_type = 'line'
+
+        attr_reader :offenses, :config
+
+        # Initialize a result object with parsed validator data
+        # @param parsed_data [Array<Hash>] Array of offense hashes from validator parser
+        # @param config [Config, nil] Configuration object for severity lookup
+        def initialize(parsed_data, config = nil)
+          @parsed_data = Array(parsed_data)
+          @config = config
+          @offenses = build_offenses
+        end
+
+        # Count of offenses
+        # @return [Integer] number of offenses
+        def count
+          @offenses.count
+        end
+
+        # Check if there are no offenses
+        # @return [Boolean] true if no offenses
+        def empty?
+          @offenses.empty?
+        end
+
+        # Delegate array methods to offenses for convenience
+        # @return [Array] mapped offenses
+        def map(&)
+          @offenses.map(&)
+        end
+
+        # Delegate each to offenses
+        # @return [Array] offenses
+        def each(&)
+          @offenses.each(&)
+        end
+
+        # Full validator name in format 'Category/ValidatorName'
+        # Extracted from the class path
+        # @return [String] validator name for config lookup
+        def validator_name
+          # Extract from class path: Validators::Tags::Order::Result => 'Tags/Order'
+          parts = self.class.name.split('::')
+          validators_index = parts.index('Validators')
+          return '' unless validators_index
+
+          category = parts[validators_index + 1]
+          name = parts[validators_index + 2]
+          "#{category}/#{name}"
+        end
+
+        private
+
+        # Build a human-readable message for an offense
+        # Subclasses must override this method
+        # @param offense [Hash] offense data from parser
+        # @return [String] formatted message
+        def build_message(offense)
+          raise NotImplementedError, "#{self.class} must implement #build_message"
+        end
+
+        # Build array of offense hashes in unified format
+        # Merges original parsed data with standard offense fields
+        # @return [Array<Hash>] array of offense hashes
+        def build_offenses
+          @parsed_data.map do |offense_data|
+            # Start with original parsed data to preserve all fields
+            offense_data.merge(
+              severity: configured_severity,
+              type: self.class.offense_type,
+              name: computed_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
+
+        # Get configured severity or fall back to default
+        # @return [String] severity level
+        def configured_severity
+          default = self.class.default_severity
+          raise NotImplementedError, "#{self.class} must set self.default_severity" unless default
+
+          return default unless config
+
+          config.validator_severity(validator_name) || default
+        end
+
+        # Compute offense name from class attribute or derive from class name
+        # @return [String] offense name
+        def computed_offense_name
+          return self.class.offense_name if self.class.offense_name
+          return 'Unknown' unless self.class.name
+
+          self.class.name.split('::').last.sub(/Result$/, '')
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/runner.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Main runner class that orchestrates the YARD validation process
+    class Runner
+      attr_reader :config, :selection
+      attr_accessor :progress_formatter
+
+      # @param selection [Array<String>] array with ruby files to check
+      # @param config [Yard::Lint::Config] configuration object
+      def initialize(selection, config = Config.new)
+        @selection = Array(selection).flatten
+        @config = config
+        @result_builder = ResultBuilder.new(config)
+        @progress_formatter = nil
+      end
+
+      # Runs all validators and returns a Result object
+      # @return [Yard::Lint::Result] result object with all offenses
+      def run
+        raw_results = run_validators
+        parsed_results = parse_results(raw_results)
+        build_result(parsed_results)
+      end
+
+      private
+
+      # Run all validators
+      # Automatically runs all validators from ConfigLoader::ALL_VALIDATORS if enabled
+      # @return [Hash] hash with raw results from all validators
+      def run_validators
+        results = {}
+        enabled_validators = ConfigLoader::ALL_VALIDATORS.select do |name|
+          config.validator_enabled?(name)
+        end
+
+        @progress_formatter&.start(enabled_validators.size)
+
+        # Iterate through all registered validators
+        enabled_validators.each_with_index do |validator_name, index|
+          # Get the validator namespace and config
+          validator_namespace = ConfigLoader.validator_module(validator_name)
+          validator_cfg = ConfigLoader.validator_config(validator_name)
+
+          # Show progress before running validator
+          @progress_formatter&.update(index + 1, validator_name)
+
+          # Run the validator if it has a module
+          # (validators with modules have Validator classes)
+          if validator_namespace
+            run_and_store_validator(validator_namespace, validator_cfg, results, validator_name)
+          end
+        end
+
+        @progress_formatter&.finish
+
+        results
+      end
+
+      # Run a validator and store its result using the module's ID
+      # @param validator_namespace [Module] validator namespace module (e.g., Validators::Tags::Order)
+      # @param validator_config [Class] validator config class
+      # @param results [Hash] hash to store results in
+      # @param validator_name [String] full validator name for per-validator exclusions
+      def run_and_store_validator(
+        validator_namespace, validator_config, results, validator_name
+      )
+        results[validator_config.id] = run_validator(
+          validator_namespace::Validator,
+          validator_name
+        )
+      end
+
+      # Run a single validator with per-validator file filtering
+      # @param validator_class [Class] validator class to instantiate and run
+      # @param validator_name [String] full validator name for exclusions
+      # @return [Hash] hash with stdout, stderr and exit_code keys
+      def run_validator(validator_class, validator_name)
+        validator_selection = filter_files_for_validator(validator_name, selection)
+        validator_class.new(config, validator_selection).call
+      end
+
+      # Filter files for a specific validator based on per-validator exclusions
+      # @param validator_name [String] full validator name
+      # @param files [Array<String>] array of file paths
+      # @return [Array<String>] filtered array of file paths
+      def filter_files_for_validator(validator_name, files)
+        validator_excludes = config.validator_exclude(validator_name)
+        return files if validator_excludes.empty?
+
+        files.reject do |file|
+          validator_excludes.any? do |pattern|
+            File.fnmatch(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+        end
+      end
+
+      # Parse raw results from validators and create Result objects
+      # Delegates result building to ResultBuilder
+      # @param raw [Hash] hash with raw results from all validators
+      # @return [Array<Results::Base>] array of Result objects
+      def parse_results(raw)
+        results = []
+
+        # Iterate through all registered validators and build results
+        ConfigLoader::ALL_VALIDATORS.each do |validator_name|
+          next unless config.validator_enabled?(validator_name)
+
+          result = @result_builder.build(validator_name, raw)
+          results << result if result
+        end
+
+        results
+      end
+
+      # Build final result object
+      # @param results [Array<Results::Base>] array of validator result objects
+      # @return [Results::Aggregate] aggregate result object
+      def build_result(results)
+        Results::Aggregate.new(results, config)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Validators for checking different aspects of YARD documentation
+    module Validators
+      # Base YARD validator class
+      class Base
+        # Class-level cache shared across ALL validator classes
+        # Must be stored on Base itself, not on subclasses
+        @shared_command_cache = nil
+
+        # Default YARD command options that we need to use
+        DEFAULT_OPTIONS = [
+          '--charset utf-8',
+          '--markup markdown',
+          '--no-progress'
+        ].freeze
+
+        # String with a temp dir to store the YARD database
+        # @note We run YARD multiple times and in order not to rebuild db over and over
+        #   again but reuse the same one, we have a single tmp dir for it
+        YARDOC_TEMP_DIR = Dir.mktmpdir.freeze
+
+        private_constant :YARDOC_TEMP_DIR
+
+        attr_reader :config, :selection
+
+        class << self
+          # Lazy-initialized command cache shared across all validator instances
+          # This allows different validators to reuse results from identical YARD commands
+          # @return [CommandCache] the command cache instance
+          def command_cache
+            # Use Base's cache, not subclass's cache
+            Base.instance_variable_get(:@shared_command_cache) ||
+              Base.instance_variable_set(:@shared_command_cache, CommandCache.new)
+          end
+
+          # Reset the command cache (primarily for testing)
+          # @return [void]
+          def reset_command_cache!
+            Base.instance_variable_set(:@shared_command_cache, nil)
+          end
+
+          # Clear the YARD database (primarily for testing)
+          # @return [void]
+          def clear_yard_database!
+            return unless defined?(YARDOC_TEMP_DIR)
+
+            FileUtils.rm_rf(Dir.glob(File.join(YARDOC_TEMP_DIR, '*')))
+          end
+        end
+
+        # @param config [Yard::Lint::Config] configuration object
+        # @param selection [Array<String>] array with ruby files we want to check
+        def initialize(config, selection)
+          @config = config
+          @selection = selection
+        end
+
+        # Performs the validation and returns raw results
+        # @return [Hash] hash with stdout, stderr and exit_code keys
+        def call
+          # There might be a case when there were no files because someone ignored all
+          # then we need to return empty result
+          return raw if selection.nil? || selection.empty?
+
+          # Anything that goes to shell needs to be escaped
+          escaped_file_names = escape(selection).join(' ')
+
+          yard_cmd(YARDOC_TEMP_DIR, escaped_file_names)
+        end
+
+        private
+
+        # @return [String] all arguments with which YARD command should be executed
+        def shell_arguments
+          validator_name = self.class.name.split('::').then do |parts|
+            idx = parts.index('Validators')
+            next config.options unless idx && parts[idx + 1] && parts[idx + 2]
+
+            "#{parts[idx + 1]}/#{parts[idx + 2]}"
+          end
+
+          yard_options = config.validator_yard_options(validator_name)
+          args = escape(yard_options).join(' ')
+          "#{args} #{DEFAULT_OPTIONS.join(' ')}"
+        end
+
+        # @param array [Array] escape all elements in an array
+        # @return [Array] array with escaped elements
+        def escape(array)
+          array.map { |cmd| Shellwords.escape(cmd) }
+        end
+
+        # Builds a raw hash that can be used for further processing
+        # @param stdout [String, Hash, Array] anything that we want to return as stdout
+        # @param stderr [String, Hash, Array] any errors that occurred
+        # @param exit_code [Integer, false] result exit code or false if we want to decide it based
+        #   on the stderr content
+        # @return [Hash] hash with stdout, stderr and exit_code keys
+        def raw(stdout = '', stderr = '', exit_code = false)
+          {
+            stdout: stdout,
+            stderr: stderr,
+            exit_code: exit_code || (stderr.empty? ? 0 : 1)
+          }
+        end
+
+        # Executes a shell command and returns the result
+        # Routes through command cache to avoid duplicate executions
+        # @param cmd [String] shell command to execute
+        # @return [Hash] hash with stdout, stderr and exit_code keys
+        def shell(cmd)
+          self.class.command_cache.execute(cmd)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Base configuration class for validators
+      # Provides common class attributes for all validators
+      class Config
+        class << self
+          # Unique identifier for this validator
+          # @return [Symbol] validator identifier
+          attr_accessor :id
+
+          # Default configuration for this validator
+          # @return [Hash] default configuration hash
+          attr_accessor :defaults
+
+          # Validators to combine with this one
+          # @return [Array<String>] validator names to combine, empty array for standalone
+          def combines_with
+            @combines_with ||= []
+          end
+
+          # Set validators to combine with
+          attr_writer :combines_with
+        end
+      end
+    end
+  end
+end