yard-lint 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95017b70fd77952580b3bf10466c79efff2fb1bbd353d1ba49ce84eab7feb5e9
-  data.tar.gz: 0e5015d8cd2b15b38ccc98d149b3b923997c3952ccc8d799050e51e226d8f14b
+  metadata.gz: 72ea0cf00858078029ca28144f64d7722abcf1a646e1365560542a064a37de24
+  data.tar.gz: 2d68009b8610f26b2bfaeb053692f36a714e96ff145cc60c71ed5b2c01c2a43c
 SHA512:
-  metadata.gz: d4825147326c85f9af2faaa95200f797321e06d12bbfe4063ea5b0acd851496bc541546d0885ccdd3d674242670a573be396bc4ae454361a266cadc240c813e8
-  data.tar.gz: cb1fa4762efdbecfc0265791a93ffb3ef4a9668e9a6905da29acb966f3bbd650ebd7b21ccb826a5dab2dd972762d4f642e17ecccd986d22354af4837633991cd
+  metadata.gz: 48313464b85f0d161d39cf151fbbc681fcb5b8271efcc87a371f72199f692c6a75bf24f478dd169ad53babe987c43f88987cc89d51835085db7180eb0906a2f1
+  data.tar.gz: c2fa9aa46f81613ee4aacdee0dd6aba4492d61bb9776daf11c7754b94aec7011a5337ccfbe937b136004d240974b0fa336c406d91bb0982dc322235c02b1fdc8

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # YARD-Lint Changelog
 
+## 1.2.0 (2025-11-12)
+- **[Fix]** Add Ruby 3.5+ compatibility without requiring IRB gem dependency
+  - Ruby 3.5 moved IRB out of default gems, requiring explicit installation
+  - YARD's legacy parser depends on `IRB::Notifier` for debug output
+  - Created lightweight `IRB::Notifier` shim to satisfy YARD without full IRB gem
+  - Shim tries to load real IRB first, only provides fallback if LoadError occurs
+  - Does not override or interfere with real IRB gem when present
+  - Safe to use in applications that depend on yard-lint and also use IRB
+  - Shim automatically loaded in subprocesses via RUBYOPT environment variable
+  - Avoids adding IRB and its transitive dependencies to supply chain
+  - All 977 tests pass on Ruby 3.5.0-preview1 without IRB gem
+- **[Feature]** Add Documentation Coverage Statistics with minimum threshold enforcement
+  - `--min-coverage PERCENT` - Fail if documentation coverage is below threshold (0-100)
+  - `--stats` flag now displays coverage metrics (total objects, documented, undocumented, percentage)
+  - `MinCoverage` configuration option in `.yard-lint.yml` under `AllValidators` section
+  - CLI flag overrides config file setting for flexibility in CI/CD pipelines
+  - Coverage calculation uses YARD queries to count documented vs undocumented objects
+  - Works seamlessly with diff mode (--diff, --staged, --changed) to calculate coverage for changed files only
+  - Exit code 1 when coverage is below minimum threshold, even if no linting offenses found
+  - Summary-only output in --quiet mode shows coverage with pass/fail status
+  - Comprehensive unit and integration test coverage for all scenarios
+  - Performance optimized with auto-cleanup temp directories for large codebases
+- **[Feature]** Add Diff Mode for incremental linting - only analyze files that changed
+  - `--diff [REF]` - Lint only files changed since REF (auto-detects main/master if not specified)
+  - `--staged` - Lint only staged files (git index)
+  - `--changed` - Lint only uncommitted files
+  - Enables practical usage in large legacy codebases
+  - Perfect for CI/CD pipelines (only check what changed in PR)
+  - Ideal for pre-commit hooks (only check staged files)
+  - Auto-detects main/master branch with fallback to master
+  - Applies global exclusion patterns to git diff results
+  - Silently skips deleted files
+  - Returns clean result when no files are changed
+  - Uses shell-based git commands via Open3 (no new dependencies)
+  - Configuration support via `AllValidators.DiffMode` section
+  - Mutually exclusive diff flags (--diff, --staged, --changed)
+
 ## 1.1.0 (2025-11-11)
 - **[Feature]** Add `Tags/ExampleSyntax` validator to validate Ruby syntax in `@example` tags
   - Uses Ruby 3.2's `RubyVM::InstructionSequence.compile()` to parse example code

data/README.md

@@ -79,16 +79,124 @@ With options:
 
 ```bash
 # Use a specific config file
-yard-lint --config config/yard-lint.yml lib/
+yard-lint lib/ --config config/yard-lint.yml
 
 # Output as JSON
-yard-lint --format json lib/ > report.json
+yard-lint lib/ --format json > report.json
 
 # Generate config file (use --force to overwrite existing)
 yard-lint --init
 yard-lint --init --force
 ```
 
+### Diff Mode (Incremental Linting)
+
+Lint only files that changed - perfect for large projects, CI/CD, and pre-commit hooks:
+
+```bash
+# Lint only files changed since main branch (auto-detects main/master)
+yard-lint lib/ --diff
+
+# Lint only files changed since specific branch/commit
+yard-lint lib/ --diff develop
+yard-lint lib/ --diff HEAD~3
+
+# Lint only staged files (perfect for pre-commit hooks)
+yard-lint lib/ --staged
+
+# Lint only uncommitted files
+yard-lint lib/ --changed
+```
+
+**Use Cases:**
+
+**Pre-commit Hook:**
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+bundle exec yard-lint lib/ --staged --fail-on-severity error
+```
+
+**GitHub Actions CI/CD:**
+```yaml
+name: YARD Lint
+on: [pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history for --diff
+      - name: Run YARD-Lint on changed files
+        run: bundle exec yard-lint lib/ --diff origin/${{ github.base_ref }}
+```
+
+**Legacy Codebase Incremental Adoption:**
+```bash
+# Only enforce rules on NEW code
+yard-lint lib/ --diff main
+```
+
+### Documentation Coverage Statistics
+
+Monitor and enforce minimum documentation coverage thresholds:
+
+```bash
+# Show coverage statistics with --stats flag
+yard-lint lib/ --stats
+
+# Output:
+# Documentation Coverage: 85.5%
+#   Total objects:      120
+#   Documented:         102
+#   Undocumented:       18
+
+# Enforce minimum coverage threshold (fails if below)
+yard-lint lib/ --min-coverage 80
+
+# Use with diff mode to check coverage only for changed files
+yard-lint lib/ --diff main --min-coverage 90
+
+# Quiet mode shows only summary with coverage
+yard-lint lib/ --quiet --min-coverage 80
+```
+
+**Configuration File:**
+```yaml
+# .yard-lint.yml
+AllValidators:
+  # Fail if documentation coverage is below this percentage
+  MinCoverage: 80.0
+```
+
+**CI/CD Pipeline Example:**
+```yaml
+name: Documentation Quality
+on: [pull_request]
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check documentation coverage for new code
+        run: |
+          bundle exec yard-lint \
+            lib/ \
+            --diff origin/${{ github.base_ref }} \
+            --min-coverage 90 \
+            --quiet
+```
+
+**Key Features:**
+- Calculates percentage of documented classes, modules, and methods
+- CLI `--min-coverage` flag overrides config file setting
+- Exit code 1 if coverage is below threshold
+- Works with diff mode to enforce coverage only on changed files
+- Performance optimized with auto-cleanup temp directories for large codebases
+
 ## Configuration
 
 YARD-Lint is configured via a `.yard-lint.yml` configuration file (similar to `.rubocop.yml`).
@@ -116,6 +224,13 @@ AllValidators:
   # Exit code behavior (error, warning, convention, never)
   FailOnSeverity: warning
 
+  # Diff mode settings
+  DiffMode:
+    # Default base ref for --diff (auto-detects main/master if not specified)
+    DefaultBaseRef: ~
+    # Include untracked files in diff mode (not yet implemented)
+    IncludeUntracked: false
+
 # Individual validator configuration
 Documentation/UndocumentedObjects:
   Description: 'Checks for classes, modules, and methods without documentation.'
@@ -273,7 +388,7 @@ YARD-Lint will automatically search for `.yard-lint.yml` in the current director
 You can specify a different config file:
 
 ```bash
-yard-lint --config path/to/config.yml lib/
+yard-lint lib/ --config path/to/config.yml
 ```
 
 #### Configuration Inheritance

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,32 @@ 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
@@ -47,6 +70,13 @@ 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!
@@ -96,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]
@@ -113,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

data/lib/yard/lint/config_generator.rb

@@ -27,6 +27,15 @@ module Yard
           # 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.'

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
 

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/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.1.0'
+    VERSION = '1.2.0'
   end
 end

data/lib/yard/lint.rb

@@ -19,10 +19,20 @@ module Yard
       # @param config_file [String, nil] path to config file
       #   (auto-loads .yard-lint.yml if not specified)
       # @param progress [Boolean] show progress indicator (default: true for TTY)
+      # @param diff [Hash, nil] diff mode options
+      #   - :mode [Symbol] one of :ref, :staged, :changed
+      #   - :base_ref [String, nil] base ref for :ref mode (auto-detects main/master if nil)
       # @return [Yard::Lint::Result] result object with offenses
-      def run(path:, config: nil, config_file: nil, progress: nil)
+      def run(path:, config: nil, config_file: nil, progress: nil, diff: nil)
         config ||= load_config(config_file)
-        files = expand_path(path, config)
+
+        # Determine files to lint based on diff mode or normal path expansion
+        files = if diff
+                  get_diff_files(diff, path, config)
+                else
+                  expand_path(path, config)
+                end
+
         runner = Runner.new(files, config)
 
         # Enable progress by default if output is a TTY
@@ -45,6 +55,32 @@ module Yard
         end
       end
 
+      # Get files from git diff based on diff mode
+      # @param diff [Hash] diff mode options
+      # @param path [String, Array<String>] path or array of paths to filter within
+      # @param config [Yard::Lint::Config] configuration object
+      # @return [Array<String>] array of absolute file paths
+      def get_diff_files(diff, path, config)
+        # Get changed files from git based on mode
+        git_files = case diff[:mode]
+                    when :ref
+                      Git.changed_files(diff[:base_ref], path)
+                    when :staged
+                      Git.staged_files(path)
+                    when :changed
+                      Git.uncommitted_files(path)
+                    else
+                      raise ArgumentError, "Unknown diff mode: #{diff[:mode]}"
+                    end
+
+        # Apply exclusion patterns
+        git_files.reject do |file|
+          config.exclude.any? do |pattern|
+            File.fnmatch(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+        end
+      end
+
       # Expand path/glob patterns into an array of files
       # @param path [String, Array<String>] path or array of paths
       # @param config [Yard::Lint::Config] configuration object

data/lib/yard-lint.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+# Load IRB notifier shim before YARD to avoid IRB dependency in Ruby 3.5+
+# This must be loaded before any YARD code is required
+require_relative 'yard/lint/ext/irb_notifier_shim'
+
 require 'zeitwerk'
 
 # Setup Zeitwerk loader for gem
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.ignore(__FILE__)
+loader.ignore("#{__dir__}/yard/lint/ext")
 loader.setup
 
 # Manually load the main module since it contains class-level methods

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: irb
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -77,7 +63,9 @@ files:
 - lib/yard/lint/config_generator.rb
 - lib/yard/lint/config_loader.rb
 - lib/yard/lint/errors.rb
+- lib/yard/lint/ext/irb_notifier_shim.rb
 - lib/yard/lint/formatters/progress.rb
+- lib/yard/lint/git.rb
 - lib/yard/lint/parsers/base.rb
 - lib/yard/lint/parsers/one_line_base.rb
 - lib/yard/lint/parsers/two_line_base.rb
@@ -85,6 +73,7 @@ files:
 - lib/yard/lint/results/aggregate.rb
 - lib/yard/lint/results/base.rb
 - lib/yard/lint/runner.rb
+- lib/yard/lint/stats_calculator.rb
 - lib/yard/lint/validators/base.rb
 - lib/yard/lint/validators/config.rb
 - lib/yard/lint/validators/documentation/markdown_syntax.rb