yard-lint 1.0.0 → 1.2.0

data/bin/yard-lint

@@ -8,6 +8,7 @@ require 'yard-lint'
 
 options = {}
 config_file = nil
+diff_mode = nil
 
 OptionParser.new do |opts|
   opts.banner = 'Usage: yard-lint [options] PATH'
@@ -28,10 +29,40 @@ OptionParser.new do |opts|
     options[:stats] = true
   end
 
+  opts.on('--min-coverage PERCENT', Float, 'Minimum documentation coverage required (0-100)') do |percent|
+    options[:min_coverage] = percent
+  end
+
   opts.on('--[no-]progress', 'Show progress indicator (default: auto)') do |value|
     options[:progress] = value
   end
 
+  opts.separator ''
+  opts.separator 'Diff mode options (mutually exclusive):'
+
+  opts.on('--diff [REF]', 'Lint only files changed since REF (default: main/master auto-detected)') do |ref|
+    diff_mode = { mode: :ref, base_ref: ref }
+  end
+
+  opts.on('--staged', 'Lint only staged files (git index)') do
+    diff_mode = { mode: :staged }
+  end
+
+  opts.on('--changed', 'Lint only uncommitted files') do
+    diff_mode = { mode: :changed }
+  end
+
+  opts.separator ''
+  opts.separator 'Other options:'
+
+  opts.on('--init', 'Generate .yard-lint.yml config file with defaults') do
+    options[:init] = true
+  end
+
+  opts.on('--force', 'Force overwrite when using --init') do
+    options[:force] = true
+  end
+
   opts.on('-v', '--version', 'Show version') do
     puts "yard-lint #{Yard::Lint::VERSION}"
     exit
@@ -39,10 +70,29 @@ OptionParser.new do |opts|
 
   opts.on('-h', '--help', 'Show this help') do
     puts opts
+    puts
+    puts 'Examples:'
+    puts '  yard-lint lib/                          # Lint all files in lib/'
+    puts '  yard-lint --diff main lib/              # Lint only files changed since main branch'
+    puts '  yard-lint --staged lib/                 # Lint only staged files'
+    puts '  yard-lint --changed lib/                # Lint only uncommitted files'
+    puts '  yard-lint --format json lib/            # Output in JSON format'
     exit
   end
 end.parse!
 
+# Handle --init flag
+if options[:init]
+  if Yard::Lint::ConfigGenerator.generate(force: options[:force])
+    puts 'Created .yard-lint.yml with default configuration'
+    exit 0
+  else
+    puts 'Error: .yard-lint.yml already exists'
+    puts 'Use --init --force to overwrite'
+    exit 1
+  end
+end
+
 # Get path argument
 path = ARGV[0]
 
@@ -76,12 +126,28 @@ end
 Yard::Lint::Validators::Base.reset_command_cache!
 Yard::Lint::Validators::Base.clear_yard_database!
 
-# Run the linter with config_file (it will be loaded internally)
-result = Yard::Lint.run(
-  path: path,
-  config_file: config_file,
-  progress: options[:progress]
-)
+# Load config and apply CLI overrides
+config = if config_file
+           Yard::Lint::Config.from_file(config_file)
+         else
+           Yard::Lint::Config.load || Yard::Lint::Config.new
+         end
+
+# Apply CLI min_coverage override if provided
+config.min_coverage = options[:min_coverage] if options[:min_coverage]
+
+# Run the linter
+begin
+  result = Yard::Lint.run(
+    path: path,
+    config: config,
+    progress: options[:progress],
+    diff: diff_mode
+  )
+rescue Yard::Lint::Git::Error => e
+  puts "Git error: #{e.message}"
+  exit 1
+end
 
 # Format and display results
 case options[:format]
@@ -93,14 +159,40 @@ when 'json'
   })
   exit result.exit_code
 when 'text', nil
+  # Calculate coverage stats if requested or configured
+  coverage = result.documentation_coverage if options[:stats] || options[:min_coverage] || config.min_coverage
+
+  # Show coverage stats if available
+  if coverage && (options[:stats] || options[:quiet])
+    puts "\nDocumentation Coverage: #{coverage[:coverage].round(2)}%"
+    puts "  Total objects:      #{coverage[:total]}"
+    puts "  Documented:         #{coverage[:documented]}"
+    puts "  Undocumented:       #{coverage[:total] - coverage[:documented]}"
+
+    if config.min_coverage
+      if coverage[:coverage] >= config.min_coverage
+        puts "  Status:             ✓ Meets minimum (#{config.min_coverage}%)"
+      else
+        puts "  Status:             ✗ Below minimum (#{config.min_coverage}%)"
+      end
+    end
+    puts
+  end
+
   if result.clean?
-    puts 'No offenses found'
+    # Still check coverage requirement even if no offenses
+    if coverage && config.min_coverage && coverage[:coverage] < config.min_coverage
+      puts "Error: Documentation coverage #{coverage[:coverage].round(2)}% is below minimum #{config.min_coverage}%"
+      exit result.exit_code
+    end
+
+    puts 'No offenses found' unless options[:quiet]
     exit 0
   else
     # Show statistics if requested or in quiet mode
     if options[:stats] || options[:quiet]
       stats = result.statistics
-      puts "\n#{result.count} offense(s) detected"
+      puts "#{result.count} offense(s) detected"
       puts "  Errors:      #{stats[:error]}"
       puts "  Warnings:    #{stats[:warning]}"
       puts "  Conventions: #{stats[:convention]}"

data/lib/yard/lint/command_cache.rb

@@ -58,7 +58,10 @@ module Yard
       # @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)
+        # Set up environment to load IRB shim before YARD (Ruby 3.5+ compatibility)
+        env = build_environment_with_shim
+
+        stdout, stderr, status = Open3.capture3(env, command_string)
         {
           stdout: stdout,
           stderr: stderr,
@@ -66,6 +69,19 @@ module Yard
         }
       end
 
+      # Build environment hash with RUBYOPT to load IRB shim
+      # This ensures the shim is loaded in subprocesses (like yard list commands)
+      # @return [Hash] environment variables for command execution
+      def build_environment_with_shim
+        shim_path = File.expand_path('ext/irb_notifier_shim.rb', __dir__)
+        rubyopt = "-r#{shim_path}"
+
+        # Preserve existing RUBYOPT if present
+        rubyopt = "#{ENV['RUBYOPT'].strip} #{rubyopt}" if ENV['RUBYOPT']
+
+        { 'RUBYOPT' => rubyopt }
+      end
+
       # Deep clone a hash to prevent modifications to cached data
       # @param hash [Hash] the hash to clone
       # @return [Hash] deep cloned hash

data/lib/yard/lint/config.rb

@@ -129,6 +129,19 @@ module Yard
         all_validators['FailOnSeverity'] || 'warning'
       end
 
+      # Diff mode default base ref (main or master)
+      # @return [String, nil] default base ref for diff mode
+      def diff_mode_default_base_ref
+        diff_config = all_validators['DiffMode'] || {}
+        diff_config['DefaultBaseRef']
+      end
+
+      # Minimum documentation coverage percentage required
+      # @return [Float, nil] minimum coverage percentage (0-100) or nil if not set
+      def min_coverage
+        all_validators['MinCoverage']
+      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
@@ -192,6 +205,13 @@ module Yard
         @raw_config['AllValidators']['FailOnSeverity'] = value
       end
 
+      # Set minimum coverage percentage
+      # @param value [Float] minimum coverage percentage (0-100)
+      def min_coverage=(value)
+        @raw_config['AllValidators'] ||= {}
+        @raw_config['AllValidators']['MinCoverage'] = 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
@@ -199,8 +219,6 @@ module Yard
         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

data/lib/yard/lint/config_generator.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Generates default .yard-lint.yml configuration file
+    class ConfigGenerator
+      # Default configuration template
+      DEFAULT_CONFIG = <<~YAML
+        # YARD-Lint Configuration
+        # See https://github.com/mensfeld/yard-lint for documentation
+
+        # Global settings for all validators
+        AllValidators:
+          # YARD command-line options (applied to all validators by default)
+          YardOptions:
+            - --private
+            - --protected
+
+          # Global file exclusion patterns
+          Exclude:
+            - '\\.git'
+            - 'vendor/**/*'
+            - 'node_modules/**/*'
+            - 'spec/**/*'
+            - 'test/**/*'
+
+          # Exit code behavior (error, warning, convention, never)
+          FailOnSeverity: warning
+
+          # Minimum documentation coverage percentage (0-100)
+          # Fails if coverage is below this threshold
+          # MinCoverage: 80.0
+
+          # Diff mode settings
+          DiffMode:
+            # Default base ref for --diff (auto-detects main/master if not specified)
+            DefaultBaseRef: ~
+
+        # Documentation validators
+        Documentation/UndocumentedObjects:
+          Description: 'Checks for classes, modules, and methods without documentation.'
+          Enabled: true
+          Severity: warning
+          ExcludedMethods:
+            - 'initialize/0'  # Exclude parameter-less initialize
+            - '/^_/'          # Exclude private methods (by convention)
+
+        Documentation/UndocumentedMethodArguments:
+          Description: 'Checks for method parameters without @param tags.'
+          Enabled: true
+          Severity: warning
+
+        Documentation/UndocumentedBooleanMethods:
+          Description: 'Checks that question mark methods document their boolean return.'
+          Enabled: true
+          Severity: warning
+
+        Documentation/UndocumentedOptions:
+          Description: 'Detects methods with options hash parameters but no @option tags.'
+          Enabled: true
+          Severity: warning
+
+        Documentation/MarkdownSyntax:
+          Description: 'Detects common markdown syntax errors in documentation.'
+          Enabled: true
+          Severity: warning
+
+        # Tags validators
+        Tags/Order:
+          Description: 'Enforces consistent ordering of YARD tags.'
+          Enabled: true
+          Severity: convention
+          EnforcedOrder:
+            - param
+            - option
+            - return
+            - raise
+            - example
+
+        Tags/InvalidTypes:
+          Description: 'Validates type definitions in @param, @return, @option tags.'
+          Enabled: true
+          Severity: warning
+          ValidatedTags:
+            - param
+            - option
+            - return
+
+        Tags/TypeSyntax:
+          Description: 'Validates YARD type syntax using YARD parser.'
+          Enabled: true
+          Severity: warning
+          ValidatedTags:
+            - param
+            - option
+            - return
+            - yieldreturn
+
+        Tags/MeaninglessTag:
+          Description: 'Detects @param/@option tags on classes, modules, or constants.'
+          Enabled: true
+          Severity: warning
+          CheckedTags:
+            - param
+            - option
+          InvalidObjectTypes:
+            - class
+            - module
+            - constant
+
+        Tags/CollectionType:
+          Description: 'Validates Hash collection syntax consistency.'
+          Enabled: true
+          Severity: convention
+          EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+          ValidatedTags:
+            - param
+            - option
+            - return
+            - yieldreturn
+
+        Tags/TagTypePosition:
+          Description: 'Validates type annotation position in tags.'
+          Enabled: true
+          Severity: convention
+          CheckedTags:
+            - param
+            - option
+          # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
+          #                or 'type_first' (@param [Type] name)
+          EnforcedStyle: type_after_name
+
+        Tags/ApiTags:
+          Description: 'Enforces @api tags on public objects.'
+          Enabled: false  # Opt-in validator
+          Severity: warning
+          AllowedApis:
+            - public
+            - private
+            - internal
+
+        Tags/OptionTags:
+          Description: 'Requires @option tags for methods with options parameters.'
+          Enabled: true
+          Severity: warning
+
+        # Warnings validators - catches YARD parser errors
+        Warnings/UnknownTag:
+          Description: 'Detects unknown YARD tags.'
+          Enabled: true
+          Severity: error
+
+        Warnings/UnknownDirective:
+          Description: 'Detects unknown YARD directives.'
+          Enabled: true
+          Severity: error
+
+        Warnings/InvalidTagFormat:
+          Description: 'Detects malformed tag syntax.'
+          Enabled: true
+          Severity: error
+
+        Warnings/InvalidDirectiveFormat:
+          Description: 'Detects malformed directive syntax.'
+          Enabled: true
+          Severity: error
+
+        Warnings/DuplicatedParameterName:
+          Description: 'Detects duplicate @param tags.'
+          Enabled: true
+          Severity: error
+
+        Warnings/UnknownParameterName:
+          Description: 'Detects @param tags for non-existent parameters.'
+          Enabled: true
+          Severity: error
+
+        # Semantic validators
+        Semantic/AbstractMethods:
+          Description: 'Ensures @abstract methods do not have real implementations.'
+          Enabled: true
+          Severity: warning
+      YAML
+
+      # Generate .yard-lint.yml file in current directory
+      # @param force [Boolean] overwrite existing file if true
+      # @return [Boolean] true if file was created, false if already exists
+      def self.generate(force: false)
+        config_path = File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
+
+        if File.exist?(config_path) && !force
+          false
+        else
+          File.write(config_path, DEFAULT_CONFIG)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/ext/irb_notifier_shim.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Shim for IRB::Notifier to avoid IRB dependency in Ruby 3.5+
+#
+# YARD's legacy parser vendors old IRB code that depends on IRB::Notifier.
+# In Ruby 3.5+, IRB is no longer part of the default gems and must be explicitly installed.
+# This shim provides just enough functionality to keep YARD's legacy parser working
+# without requiring the full IRB gem as a dependency.
+#
+# The notifier is only used for debug output in YARD's legacy parser, which we don't need.
+#
+# IMPORTANT: This shim only loads if IRB::Notifier is not already defined.
+# If IRB gem is present, we use the real implementation instead.
+
+# Only load the shim if IRB::Notifier is not already defined
+unless defined?(IRB::Notifier)
+  # Try to load the real IRB notifier first
+  # If it fails (IRB not installed), we'll provide our shim
+  begin
+    # Suppress warnings during require attempt (Ruby 3.5+ warns about missing default gems)
+    original_verbose = $VERBOSE
+    $VERBOSE = nil
+    require 'irb/notifier'
+  rescue LoadError
+    # IRB not available, use our shim
+    # Mark as loaded to prevent further require attempts
+    $LOADED_FEATURES << 'irb/notifier.rb'
+
+    module IRB
+      # Minimal Notifier implementation that does nothing
+      # YARD's legacy parser uses this for debug output which we can safely ignore
+      class Notifier
+        # No-op message level constant
+        D_NOMSG = 0
+
+        class << self
+          # Returns a no-op notifier
+          # @param _prefix [String] notification prefix (ignored)
+          # @return [NoOpNotifier] a notifier that does nothing
+          def def_notifier(_prefix)
+            NoOpNotifier.new
+          end
+        end
+
+        # A notifier that silently discards all output
+        class NoOpNotifier
+          attr_accessor :level
+
+          def initialize
+            @level = Notifier::D_NOMSG
+          end
+
+          # Returns a no-op notifier for any sub-level
+          # @param _level [Integer] notification level (ignored)
+          # @param _prefix [String] notification prefix (ignored)
+          # @return [NoOpNotifier] a notifier that does nothing
+          def def_notifier(_level, _prefix)
+            NoOpNotifier.new
+          end
+
+          # Silently ignore pretty-print calls
+          # @param _obj [Object] object to pretty-print (ignored)
+          # @return [nil]
+          def pp(_obj)
+            nil
+          end
+
+          # Silently ignore print calls
+          # @param _args [Array] print arguments (ignored)
+          # @return [nil]
+          def print(*_args)
+            nil
+          end
+
+          # Silently ignore puts calls
+          # @param _args [Array] puts arguments (ignored)
+          # @return [nil]
+          def puts(*_args)
+            nil
+          end
+
+          # Silently ignore printf calls
+          # @param _args [Array] printf arguments (ignored)
+          # @return [nil]
+          def printf(*_args)
+            nil
+          end
+        end
+      end
+    end
+  ensure
+    # Restore original verbosity setting
+    $VERBOSE = original_verbose
+  end
+end

data/lib/yard/lint/git.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Git integration for diff mode functionality
+    module Git
+      # Custom error class for Git-related errors
+      class Error < StandardError; end
+
+      class << self
+        # Detect the default branch (main or master)
+        # @return [String] 'main', 'master', or nil if neither exists
+        def default_branch
+          # Try main first (modern default)
+          return 'main' if branch_exists?('main')
+          # Fall back to master (legacy default)
+          return 'master' if branch_exists?('master')
+
+          nil
+        end
+
+        # Check if a git ref exists
+        # @param ref [String] the git ref to check
+        # @return [Boolean] true if ref exists
+        def branch_exists?(ref)
+          _stdout, _stderr, status = Open3.capture3('git', 'rev-parse', '--verify', '--quiet', ref)
+          status.success?
+        end
+
+        # Get files changed since a base ref
+        # @param base_ref [String, nil] the base ref to compare against (nil for auto-detect)
+        # @param path [String] the path to filter files within
+        # @return [Array<String>] absolute paths to changed Ruby files
+        def changed_files(base_ref, path)
+          base_ref ||= default_branch
+          raise Error, 'Could not detect default branch (main/master)' unless base_ref
+
+          ensure_git_repository!
+
+          # Use three-dot diff to compare against merge base
+          stdout, stderr, status = Open3.capture3('git', 'diff', '--name-only', "#{base_ref}...HEAD")
+
+          unless status.success?
+            raise Error, "Git diff failed: #{stderr.strip}"
+          end
+
+          filter_ruby_files(stdout.split("\n"), path)
+        end
+
+        # Get staged files (files in git index)
+        # @param path [String] the path to filter files within
+        # @return [Array<String>] absolute paths to staged Ruby files
+        def staged_files(path)
+          ensure_git_repository!
+
+          # ACM filter: Added, Copied, Modified (exclude Deleted)
+          stdout, stderr, status = Open3.capture3(
+            'git', 'diff', '--cached', '--name-only', '--diff-filter=ACM'
+          )
+
+          unless status.success?
+            raise Error, "Git diff failed: #{stderr.strip}"
+          end
+
+          filter_ruby_files(stdout.split("\n"), path)
+        end
+
+        # Get uncommitted files (all changes in working directory)
+        # @param path [String] the path to filter files within
+        # @return [Array<String>] absolute paths to uncommitted Ruby files
+        def uncommitted_files(path)
+          ensure_git_repository!
+
+          # Get both staged and unstaged changes
+          stdout, stderr, status = Open3.capture3('git', 'diff', '--name-only', 'HEAD')
+
+          unless status.success?
+            raise Error, "Git diff failed: #{stderr.strip}"
+          end
+
+          filter_ruby_files(stdout.split("\n"), path)
+        end
+
+        private
+
+        # Ensure we're in a git repository
+        # @raise [Error] if not in a git repository
+        def ensure_git_repository!
+          _stdout, _stderr, status = Open3.capture3('git', 'rev-parse', '--git-dir')
+
+          return if status.success?
+
+          raise Error, 'Not a git repository'
+        end
+
+        # Filter for Ruby files within path and convert to absolute paths
+        # @param files [Array<String>] relative file paths from git
+        # @param path [String] the base path to filter within
+        # @return [Array<String>] absolute paths to Ruby files that exist
+        def filter_ruby_files(files, path)
+          base_path = File.expand_path(path)
+
+          files
+            .select { |f| f.end_with?('.rb') }
+            .map { |f| File.expand_path(f) }
+            .select { |f| File.exist?(f) } # Skip deleted files
+            .select { |f| file_within_path?(f, base_path) }
+        end
+
+        # Check if file is within the specified path
+        # @param file [String] absolute file path
+        # @param base_path [String] absolute base path
+        # @return [Boolean] true if file is within base_path
+        def file_within_path?(file, base_path)
+          # Handle both directory and file base_path
+          if File.directory?(base_path)
+            file.start_with?(base_path + '/')
+          else
+            file == base_path
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -13,14 +13,16 @@ module Yard
         # Convention severity level constant
         SEVERITY_CONVENTION = 'convention'
 
-        attr_reader :config
+        attr_reader :config, :files
 
         # 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)
+        # @param files [Array<String>, nil] array of files that were analyzed
+        def initialize(results, config = nil, files = nil)
           @results = Array(results)
           @config = config
+          @files = Array(files)
         end
 
         # Get all offenses from all validators
@@ -60,10 +62,28 @@ module Yard
           stats
         end
 
+        # Calculate documentation coverage statistics
+        # @return [Hash] coverage statistics with :total, :documented, :coverage keys
+        def documentation_coverage
+          return @documentation_coverage if defined?(@documentation_coverage)
+
+          return nil unless @config && !@files.empty?
+
+          calculator = StatsCalculator.new(@config, @files)
+          @documentation_coverage = calculator.calculate
+        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
+          # Check minimum coverage requirement first
+          if @config&.min_coverage &&
+             documentation_coverage &&
+             documentation_coverage[:coverage] < @config.min_coverage
+            return 1
+          end
+
           return 0 if offenses.empty?
           return 0 unless @config # No config means don't fail