yard-lint 0.2.0

data/lib/yard/lint/command_cache.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Cache for YARD command executions to avoid running identical commands multiple times
+    # This provides a transparent optimization layer - validators don't need to know about it
+    class CommandCache
+      def initialize
+        @cache = {}
+        @hits = 0
+        @misses = 0
+      end
+
+      # Execute a command through the cache
+      # If the command has been executed before, return cached result
+      # Otherwise execute and cache the result
+      # @param command_string [String] the shell command to execute
+      # @return [Hash] hash with stdout, stderr, exit_code keys
+      # @note Returns a deep clone to prevent validators from modifying cached data
+      def execute(command_string)
+        cache_key = generate_cache_key(command_string)
+
+        if @cache.key?(cache_key)
+          @hits += 1
+          deep_clone(@cache[cache_key])
+        else
+          @misses += 1
+          result = execute_command(command_string)
+          @cache[cache_key] = deep_clone(result)
+          result
+        end
+      end
+
+      # Get cache statistics
+      # @return [Hash] hash with hits, misses, and total executions
+      def stats
+        {
+          hits: @hits,
+          misses: @misses,
+          total: @hits + @misses,
+          saved_executions: @hits
+        }
+      end
+
+      private
+
+      # Generate a cache key for the command
+      # Normalizes the command to handle whitespace differences
+      # @param command_string [String] the command to generate key for
+      # @return [String] SHA256 hash of normalized command
+      def generate_cache_key(command_string)
+        # Normalize whitespace: collapse multiple spaces/newlines into single spaces
+        normalized = command_string.strip.gsub(/\s+/, ' ')
+        Digest::SHA256.hexdigest(normalized)
+      end
+
+      # Actually execute the command
+      # @param command_string [String] the command to execute
+      # @return [Hash] hash with stdout, stderr, exit_code keys
+      def execute_command(command_string)
+        stdout, stderr, status = Open3.capture3(command_string)
+        {
+          stdout: stdout,
+          stderr: stderr,
+          exit_code: status.exitstatus
+        }
+      end
+
+      # Deep clone a hash to prevent modifications to cached data
+      # @param hash [Hash] the hash to clone
+      # @return [Hash] deep cloned hash
+      def deep_clone(hash)
+        Marshal.load(Marshal.dump(hash))
+      end
+    end
+  end
+end

data/lib/yard/lint/config.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+# YARD Lint - comprehensive linter for YARD documentation
+module Yard
+  module Lint
+    # Configuration object for YARD Lint
+    class Config
+      attr_reader :raw_config, :validators
+
+      # Default YAML config file name
+      DEFAULT_CONFIG_FILE = '.yard-lint.yml'
+
+      # Valid severity levels for fail_on_severity
+      VALID_SEVERITIES = %w[error warning convention never].freeze
+
+      # Metadata keys to skip when merging validator configs
+      METADATA_KEYS = %w[Description StyleGuide VersionAdded VersionChanged].freeze
+
+      # @param raw_config [Hash] raw configuration hash (new hierarchical format)
+      def initialize(raw_config = {})
+        @raw_config = raw_config
+        @validators = build_validators_config
+
+        yield self if block_given?
+      end
+
+      class << self
+        # Load configuration from a YAML file
+        # @param path [String] path to YAML config file
+        # @return [Yard::Lint::Config] configuration object
+        # @raise [Yard::Lint::Errors::ConfigFileNotFoundError] if config file doesn't exist
+        def from_file(path)
+          unless File.exist?(path)
+            raise Errors::ConfigFileNotFoundError, "Config file not found: #{path}"
+          end
+
+          # Load with inheritance support
+          merged_yaml = ConfigLoader.load(path)
+
+          new(merged_yaml)
+        end
+
+        # Search for and load config file from current directory upwards
+        # @param start_path [String] directory to start searching from (default: current dir)
+        # @return [Yard::Lint::Config, nil] config if found, nil otherwise
+        def load(start_path: Dir.pwd)
+          config_path = find_config_file(start_path)
+          config_path ? from_file(config_path) : nil
+        end
+
+        # Find config file by searching upwards from start_path
+        # @param start_path [String] directory to start searching from
+        # @return [String, nil] path to config file if found
+        def find_config_file(start_path)
+          current = File.expand_path(start_path)
+          root = File.expand_path('/')
+
+          loop do
+            config_path = File.join(current, DEFAULT_CONFIG_FILE)
+            return config_path if File.exist?(config_path)
+
+            break if current == root
+
+            current = File.dirname(current)
+          end
+
+          nil
+        end
+      end
+
+      # YARD command-line options
+      # @return [Array<String>] YARD options
+      def options
+        all_validators['YardOptions'] || []
+      end
+
+      # Get YARD options for a specific validator
+      # Falls back to global options if validator doesn't specify its own
+      # @param validator_name [String] full validator name
+      # @return [Array<String>] YARD options for this validator
+      def validator_yard_options(validator_name)
+        validator_config = validators[validator_name] || {}
+        validator_config['YardOptions'] || options
+      end
+
+      # Global file exclusion patterns
+      # @return [Array<String>] exclusion patterns
+      def exclude
+        all_validators['Exclude'] || ['\.git', 'vendor/**/*', 'node_modules/**/*']
+      end
+
+      # Minimum severity level to fail on
+      # @return [String] severity level (error, warning, convention, never)
+      def fail_on_severity
+        all_validators['FailOnSeverity'] || 'warning'
+      end
+
+      # Check if a validator is enabled
+      # @param validator_name [String] full validator name (e.g., 'Tags/Order')
+      # @return [Boolean] true if validator is enabled
+      def validator_enabled?(validator_name)
+        validator_config = validators[validator_name] || {}
+        validator_config['Enabled'] != false # Default to true
+      end
+
+      # Get validator severity
+      # @param validator_name [String] full validator name
+      # @return [String] severity level for this validator
+      def validator_severity(validator_name)
+        validator_config = validators[validator_name] || {}
+        validator_config['Severity'] || 'warning'
+      end
+
+      # Get validator-specific exclude patterns
+      # @param validator_name [String] full validator name
+      # @return [Array<String>] exclusion patterns for this validator
+      def validator_exclude(validator_name)
+        validator_config = validators[validator_name] || {}
+        validator_config['Exclude'] || []
+      end
+
+      # Combined global and per-validator exclusions
+      # Returns all exclusion patterns that apply to this validator
+      # @param validator_name [String] full validator name
+      # @return [Array<String>] combined exclusion patterns (global + per-validator)
+      def validator_all_excludes(validator_name)
+        exclude + validator_exclude(validator_name)
+      end
+
+      # Get validator-specific configuration value
+      # @param validator_name [String] full validator name
+      # @param key [String] configuration key
+      # @return [Object, nil] configuration value
+      def validator_config(validator_name, key)
+        validators.dig(validator_name, key)
+      end
+
+      # Setter methods for programmatic configuration
+
+      # Set YARD options
+      # @param value [Array<String>] YARD options
+      def options=(value)
+        @raw_config['AllValidators'] ||= {}
+        @raw_config['AllValidators']['YardOptions'] = value
+      end
+
+      # Set global exclude patterns
+      # @param value [Array<String>] exclusion patterns
+      def exclude=(value)
+        @raw_config['AllValidators'] ||= {}
+        @raw_config['AllValidators']['Exclude'] = value
+      end
+
+      # Set fail on severity level
+      # @param value [String] severity level
+      def fail_on_severity=(value)
+        @raw_config['AllValidators'] ||= {}
+        @raw_config['AllValidators']['FailOnSeverity'] = value
+      end
+
+      # Allow hash-like access for convenience
+      # @param key [Symbol, String] attribute name to access
+      # @return [Object, nil] attribute value or nil if not found
+      def [](key)
+        respond_to?(key) ? send(key) : nil
+      end
+
+      private
+
+      # Generic helper to set validator configuration
+      # @param validator_name [String] full validator name (e.g., 'Tags/Order')
+      # @param key [String] configuration key
+      # @param value [Object] configuration value
+      def set_validator_config(validator_name, key, value)
+        @raw_config[validator_name] ||= {}
+        @raw_config[validator_name][key] = value
+        @validators = build_validators_config
+      end
+
+      # Generic helper to get validator configuration with default fallback
+      # @param validator_name [String] full validator name
+      # @param key [String] configuration key
+      # @return [Object, nil] configuration value or default
+      def get_validator_config_with_default(validator_name, key)
+        validator_config(validator_name, key) || begin
+          validator_cfg = ConfigLoader.validator_config(validator_name)
+          validator_cfg&.defaults&.dig(key)
+        end
+      end
+
+      # Get AllValidators section
+      # @return [Hash] AllValidators configuration
+      def all_validators
+        @raw_config['AllValidators'] || {}
+      end
+
+      # Build validators configuration from raw config
+      # @return [Hash] validators configuration
+      def build_validators_config
+        config = {}
+
+        # Start with defaults for all validators
+        ConfigLoader::ALL_VALIDATORS.each do |validator_name|
+          config[validator_name] = build_default_validator_config(validator_name)
+        end
+
+        # Apply validator-specific overrides
+        @raw_config.each do |key, value|
+          next unless key.include?('/') # Validator-specific config
+          next unless ConfigLoader::ALL_VALIDATORS.include?(key)
+
+          config[key] = merge_validator_config(config[key], value) if value.is_a?(Hash)
+        end
+
+        config
+      end
+
+      # Build default configuration for a validator
+      # @param validator_name [String] full validator name
+      # @return [Hash] default configuration
+      def build_default_validator_config(validator_name)
+        # Get defaults from validator config
+        validator_cfg = ConfigLoader.validator_config(validator_name)
+        defaults = validator_cfg&.defaults || {}
+        base = ConfigLoader::DEFAULT_VALIDATOR_CONFIG.dup
+
+        # Merge validator-specific defaults with base config
+        base.merge(defaults)
+      end
+
+      # Merge validator configuration
+      # @param base [Hash] base configuration
+      # @param override [Hash] overriding configuration
+      # @return [Hash] merged configuration
+      def merge_validator_config(base, override)
+        result = base.dup
+
+        override.each do |key, value|
+          # Skip metadata keys
+          next if METADATA_KEYS.include?(key)
+
+          result[key] = if value.is_a?(Array) && result[key].is_a?(Array)
+                          value # Array replacement
+                        elsif value.is_a?(Hash) && result[key].is_a?(Hash)
+                          result[key].merge(value)
+                        else
+                          value
+                        end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/yard/lint/config_loader.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Handles loading and merging of configuration files with inheritance support
+    class ConfigLoader
+      # Inheritance keys to skip when merging configs
+      INHERITANCE_KEYS = %w[inherit_from inherit_gem].freeze
+
+      class << self
+        # Get the validator namespace module for a given validator name
+        # @param validator_name [String] validator name (e.g., 'Tags/Order')
+        # @return [Module, nil] validator namespace module or nil if doesn't exist
+        def validator_module(validator_name)
+          category, name = validator_name.split('/')
+          module_path = "Validators::#{category}::#{name}"
+
+          module_path.split('::').reduce(Yard::Lint) do |mod, const_name|
+            return nil unless mod.const_defined?(const_name)
+
+            mod.const_get(const_name)
+          end
+        end
+
+        # Get the validator config for a given validator name
+        # Dynamically resolves the config class based on the validator name
+        # @param validator_name [String] validator name (e.g., 'Tags/Order')
+        # @return [Class, nil] validator config class or nil if doesn't exist
+        def validator_config(validator_name)
+          namespace = validator_module(validator_name)
+          return nil unless namespace
+
+          # Return the Config class from within the validator namespace
+          namespace.const_defined?(:Config) ? namespace.const_get(:Config) : nil
+        end
+
+        # Auto-discover validators from the codebase
+        # Scans the validators directory and loads all validator modules that have
+        # an .id method and .defaults method (indicating they're valid validators)
+        # @return [Hash<String, Array<String>>] hash of category names to validator names
+        def discover_validators
+          categories = Hash.new { |h, k| h[k] = [] }
+
+          validators_path = File.join(__dir__, 'validators')
+
+          # Find all validator module files (e.g., validators/tags/order.rb)
+          Dir.glob(File.join(validators_path, '*', '*.rb')).each do |file_path|
+            # Require the validator module file to ensure it's loaded
+            require file_path
+
+            # Extract category and validator name from path
+            # e.g., .../validators/tags/order.rb -> ['tags', 'order']
+            relative_path = file_path.sub("#{validators_path}/", '')
+            parts = relative_path.sub('.rb', '').split('/')
+            category_dir = parts[0]
+            validator_dir = parts[1]
+
+            # Convert to proper casing:
+            # 'tags' -> 'Tags', 'undocumented_objects' -> 'UndocumentedObjects'
+            category = category_dir.split('_').map(&:capitalize).join
+            validator = validator_dir.split('_').map(&:capitalize).join
+
+            # Construct the validator name
+            validator_name = "#{category}/#{validator}"
+
+            # Verify it's a valid validator by checking if it has a Config class
+            cfg = validator_config(validator_name)
+            # Every validator must have a Config with id and defaults
+            categories[category] << validator_name if cfg && cfg.id && cfg.defaults
+          end
+
+          # Sort for consistent ordering
+          categories.transform_values(&:sort).sort.to_h
+        end
+
+        # Load configuration from file with inheritance support
+        # @param path [String] path to configuration file
+        # @return [Hash] merged configuration hash
+        def load(path)
+          new(path).load
+        end
+      end
+
+      # All validator names (auto-discovered from codebase structure)
+      ALL_VALIDATORS = discover_validators.values.flatten.freeze
+
+      # Default configuration for each validator
+      DEFAULT_VALIDATOR_CONFIG = {
+        'Enabled' => true,
+        'Severity' => nil, # Will use validator's default or department fallback
+        'Exclude' => []
+      }.freeze
+
+      # @param path [String] path to configuration file
+      def initialize(path)
+        @path = path
+        @loaded_files = []
+      end
+
+      # Load and merge configuration with inheritance
+      # @return [Hash] final merged configuration
+      def load
+        load_file(@path)
+      end
+
+      private
+
+      # Load a single configuration file and handle inheritance
+      # @param path [String] path to configuration file
+      # @return [Hash] configuration hash with inheritance resolved
+      # @raise [Yard::Lint::Errors::CircularDependencyError] if circular dependency detected
+      def load_file(path)
+        # Prevent circular dependencies
+        if @loaded_files.include?(path)
+          raise Errors::CircularDependencyError, "Circular dependency detected: #{path}"
+        end
+
+        @loaded_files << path
+
+        yaml = YAML.load_file(path) || {}
+
+        # Handle inheritance
+        base_config = load_inherited_configs(yaml, File.dirname(path))
+
+        # Merge current config over inherited config
+        merge_configs(base_config, yaml)
+      end
+
+      # Load all inherited configurations
+      # @param yaml [Hash] current configuration hash
+      # @param base_dir [String] directory containing the config file
+      # @return [Hash] merged inherited configuration
+      def load_inherited_configs(yaml, base_dir)
+        config = {}
+
+        # Load inherit_from (local files)
+        if yaml['inherit_from']
+          inherit_from = Array(yaml['inherit_from'])
+          inherit_from.each do |file|
+            inherited_path = File.expand_path(file, base_dir)
+            if File.exist?(inherited_path)
+              inherited = load_file(inherited_path)
+              config = merge_configs(config, inherited)
+            end
+          end
+        end
+
+        # Load inherit_gem (gem-based configs)
+        yaml['inherit_gem']&.each do |gem_name, gem_file|
+          inherited = load_gem_config(gem_name, gem_file)
+          config = merge_configs(config, inherited) if inherited
+        end
+
+        config
+      end
+
+      # Load configuration from a gem
+      # @param gem_name [String] name of the gem
+      # @param gem_file [String] relative path within the gem
+      # @return [Hash, nil] configuration hash or nil if not found
+      def load_gem_config(gem_name, gem_file)
+        gem_spec = Gem::Specification.find_by_name(gem_name)
+        config_path = File.join(gem_spec.gem_dir, gem_file)
+
+        return nil unless File.exist?(config_path)
+
+        load_file(config_path)
+      rescue Gem::MissingSpecError
+        warn "Warning: Gem '#{gem_name}' not found for configuration inheritance"
+        nil
+      end
+
+      # Merge two configuration hashes
+      # @param base [Hash] base configuration
+      # @param override [Hash] overriding configuration
+      # @return [Hash] merged configuration
+      def merge_configs(base, override)
+        result = base.dup
+
+        override.each do |key, value|
+          # Skip inheritance keys in merged result
+          next if INHERITANCE_KEYS.include?(key)
+
+          result[key] = if value.is_a?(Hash) && result[key].is_a?(Hash)
+                          merge_configs(result[key], value)
+                        elsif value.is_a?(Array) && result[key].is_a?(Array)
+                          # For arrays, override completely (RuboCop behavior)
+                          value
+                        else
+                          value
+                        end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/yard/lint/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Namespace for all yard-lint errors
+    module Errors
+      # Base error class for all yard-lint errors
+      class BaseError < StandardError; end
+
+      # Raised when a configuration file is not found
+      class ConfigFileNotFoundError < BaseError; end
+
+      # Raised when a circular dependency is detected in configuration inheritance
+      class CircularDependencyError < BaseError; end
+    end
+  end
+end

data/lib/yard/lint/formatters/progress.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Output formatters for displaying linting progress and results
+    module Formatters
+      # Simple progress formatter that shows which validator is running
+      # Similar to RuboCop's progress display
+      class Progress
+        # Initialize progress formatter
+        # @param output [IO] output stream (default: $stdout)
+        def initialize(output = $stdout)
+          @output = output
+          @total = 0
+          @current = 0
+        end
+
+        # Start progress display
+        # @param total [Integer] total number of validators
+        def start(total)
+          @total = total
+          @current = 0
+          @output.print "Inspecting with #{total} validators\n"
+        end
+
+        # Update progress with current validator
+        # @param current [Integer] current validator number
+        # @param validator_name [String] name of the validator
+        def update(current, validator_name)
+          @current = current
+          # Clear line and show progress
+          @output.print "\r\e[K" # Clear line
+          @output.print format(
+            '[%<current>d/%<total>d] %<name>s',
+            current: current,
+            total: @total,
+            name: validator_name
+          )
+          @output.flush
+        end
+
+        # Finish progress display
+        def finish
+          @output.print "\r\e[K" # Clear the progress line
+          @output.flush
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Parsers for extracting offense details from YARD command output
+    module Parsers
+      # Base class used for all the subparsers of a yard parser
+      class Base
+        class << self
+          attr_accessor :regexps
+        end
+
+        # @param string [String] string from which we want to extract informations
+        # @param regexp_name [Symbol] name of a regexp used to extract a given information
+        # @return [Array<String>] array with extracted details or empty array if there's
+        #   nothing worth extracting
+        def match(string, regexp_name)
+          string.match(self.class.regexps[regexp_name])&.captures || []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Parsers
+      # Base class for all one line warnings parsers
+      class OneLineBase < 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, :message).last,
+              location: match(warning, :location).last,
+              line: match(warning, :line).last.to_i
+            }
+          end
+        end
+
+        private
+
+        # @param rows [Array<String>] array with lines of output from yard stats
+        # @return [Array<String>] Array with rows that match the pattern
+        def classify(rows)
+          rows.grep(self.class.regexps[:general])
+        end
+      end
+    end
+  end
+end