yard-lint 1.11.0 → 1.13.0

data/README.md

@@ -114,8 +114,14 @@ yard-lint --auto-gen-config
 yard-lint lib/
 
 # Fix violations incrementally by removing exclusions from .yard-lint-todo.yml
+
+# Fail (exit 1) when .yard-lint-todo.yml has entries that no longer match any offense
+# (use the PATH of your normal run; a PATH only limits which entries are reported)
+yard-lint --check-todo lib/
 ```
 
+`.yard-lint-todo.yml` is written and read next to the loaded `.yard-lint.yml` (or in the current directory without one), and its entries are relative to that directory, so the baseline works from any directory you run yard-lint in.
+
 **Learn more:** [Incremental Adoption Guide](https://github.com/mensfeld/yard-lint/wiki/Incremental-Adoption)
 
 ### Check Documentation Coverage
@@ -143,6 +149,14 @@ yard-lint lib/ --only Tags/Order,Documentation/UndocumentedObjects
 
 **Learn more:** [Advanced Usage Guide](https://github.com/mensfeld/yard-lint/wiki/Advanced-Usage)
 
+### Explain a Validator
+
+Print what a validator checks, its default severity, configuration options, and Bad/Good examples directly in the terminal - no need to open the wiki. The explanation is sourced from the validator's own YARD documentation.
+
+```bash
+yard-lint --explain Tags/TypeSyntax
+```
+
 ### Lint from stdin (LSP / Editor Integration)
 
 Pass source bytes directly without reading from disk. The `path` argument is still required - it governs config resolution, exclusion matching, and offense location reporting.
@@ -200,6 +214,26 @@ Then `:make` lints the current file and `:cnext` / `:cprev` jump between offense
 
 Then `M-x compile` and `M-g n` / `M-g p` navigate between offenses.
 
+### SARIF Output (GitHub Code Scanning)
+
+Use `--format sarif` to emit [SARIF 2.1.0](https://sarifweb.azurewebsites.net/), the format GitHub code scanning and most result aggregators ingest. Uploading it makes yard-lint offenses appear as annotations in the PR "Files changed" view and the repository Security tab, instead of being buried in CI logs:
+
+```bash
+yard-lint --format sarif lib/ > yard-lint.sarif
+```
+
+Each rule carries its description (from the validator's own YARD docs), and severities map to SARIF levels (`error` → error, `warning` → warning, `convention` → note). Artifact paths are emitted repository-relative so GitHub maps them onto your files. In GitHub Actions, upload the file with `github/codeql-action/upload-sarif`:
+
+```yaml
+- run: bundle exec yard-lint --format sarif lib/ > yard-lint.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: yard-lint.sarif
+```
+
+(Run yard-lint from the repository root so paths resolve correctly; `continue-on-error` lets the upload step run even when offenses are found.)
+
 ## Configuration Basics
 
 Create a `.yard-lint.yml` file in your project root:
@@ -314,10 +348,35 @@ Documentation/UnderfilledLines:
 
 **Key features:**
 - Per-validator control (enable/disable, severity, exclusions)
+- Category-level defaults (enable/disable, severity, exclusions) for a whole department
 - Configuration inheritance with `inherit_from` and `inherit_gem`
 - Automatic configuration validation with helpful error messages
 - Per-validator YARD options and file exclusions
 
+**Category-level defaults:** set `Enabled` or `Severity` on a category (`Documentation`, `Tags`, `Warnings`, `Semantic`) to apply it to every validator in that department. A per-validator setting always wins over the category, which in turn wins over the validator's built-in default:
+
+```yaml
+# Make every Tags/* offense an error...
+Tags:
+  Severity: error
+
+# ...except Tags/Order, which stays a convention
+Tags/Order:
+  Severity: convention
+```
+
+A category-level `Exclude` is combined with each validator's own `Exclude` (it is not replaced by it), so these files are skipped by every `Documentation/*` validator, including one that sets its own `Exclude`:
+
+```yaml
+Documentation:
+  Exclude:
+    - 'lib/generated/**/*'
+```
+
+A category accepts only the keys `Enabled` (`true` or `false`), `Severity` and `Exclude`; an unknown key or a non-boolean `Enabled` fails configuration validation.
+
+`Exclude` patterns at every level are relative to the directory of the loaded `.yard-lint.yml` (or the current directory without one), whatever PATH or directory you run yard-lint from. A file outside that directory is matched as `../...` (with `--config config/yard-lint.yml`, write `../lib/generated/**/*`); absolute patterns also work.
+
 **Learn more:** [Complete Configuration Guide](https://github.com/mensfeld/yard-lint/wiki/Configuration)
 
 ## Catching Orphaned Documentation Comments
@@ -426,6 +485,47 @@ The validator reports one offense per wasteful paragraph and is deliberately con
 
 Unlike `LineLength` (which measures an objective property), "this line should have been longer" is a stylistic judgement. Projects that use **semantic line breaks** (one sentence or clause per line, see [sembr.org](https://sembr.org)) are never flagged - any paragraph whose non-final lines all end at a sentence boundary (`.?!:;`) is treated as intentional. Leave the validator off, or add `,` to `SentenceEndChars`, if that style is used heavily.
 
+## Catching Typos in References
+
+The `Documentation/ReferenceTypo` validator (enabled by default, severity `warning`) checks `{Foo#bar}` links in docstrings and tag text, and `@see` targets. When a reference does not resolve and a close match exists in its namespace, it reports the reference and suggests the closest name:
+
+```ruby
+# Bad - reports: Reference 'Parser#prase' does not resolve (did you mean 'Parser#parse'?)
+# Delegates to {Parser#prase}
+def call; end
+
+# Good
+# Delegates to {Parser#parse}
+def call; end
+```
+
+To keep false positives low, it skips references into namespaces YARD does not know (stdlib, other gems), methods that a loaded Ruby ancestor may define (e.g. `{#to_s}`), names with no close match, and code spans and code blocks. A bare constant such as `{Kafka}` is only compared with constants of the enclosing namespaces, never with top-level ones, so a constant of a gem YARD did not parse is not reported as a typo of a similar project name.
+
+## Checking @overload Tags
+
+YARD checks `@param` names only against the method's own signature, never the tags inside an `@overload`. The `Tags/OverloadConsistency` validator (enabled by default, severity `warning`) checks each overload against its own signature and reports:
+
+- a `@param` that names no parameter of that overload
+- a parameter with no `@param`, when the overload documents at least one other parameter (splat and block parameters are not required; a `@param` on the method docstring counts for every overload)
+- an overload with no `@return`, when another overload of the method has one and the method docstring has none
+
+```ruby
+# Bad - reports: Overload 'fetch(key)' documents @param 'name', which is not in its signature
+#                Overload 'fetch(key)' has no @param for 'key'
+# @overload fetch(key)
+#   @param name [String] the key
+#   @return [Object]
+def fetch(*args); end
+
+# Good
+# @overload fetch(key)
+#   @param key [String] the key
+#   @return [Object]
+def fetch(*args); end
+```
+
+Overloads that forward arguments (`...`) or take anonymous `*`, `**` or `&` parameters are not checked for unknown names.
+
 ## Handling Non-Standard Types
 
 By default `Tags/InvalidTypes` accepts all built-in Ruby classes, constants, and a set of YARD pseudo-types (`nil`, `true`, `false`, `self`, `void`, `Boolean`, `undefined`, `unspecified`, `unknown`). If your project uses additional type names that are not real Ruby classes - project-specific aliases, LSP extensions, or informal conventions - you can declare them via `ExtraTypes` so yard-lint does not report them as `InvalidTagType` offenses.
@@ -522,7 +622,7 @@ Configuration:
   -c, --config FILE       Path to config file (default: .yard-lint.yml)
 
 Output:
-  -f, --format FORMAT     Output format (text, json, quickfix)
+  -f, --format FORMAT     Output format (text, json, quickfix, sarif)
   -q, --quiet             Quiet mode (only show summary)
       --stats             Show documentation coverage statistics
       --[no-]progress     Show progress indicator (default: auto-detect TTY)
@@ -538,6 +638,7 @@ Diff Mode:
 
 Validators:
       --only VALIDATORS   Run only specified validators (comma-separated)
+      --explain VALIDATOR Explain what a validator checks and how to configure it
 
 Configuration Generation:
       --init              Generate .yard-lint.yml config file
@@ -546,6 +647,7 @@ Configuration Generation:
       --force             Force overwrite when using --init
       --auto-gen-config   Generate .yard-lint-todo.yml to silence existing violations
       --regenerate-todo   Regenerate .yard-lint-todo.yml (overwrites existing)
+      --check-todo        Report .yard-lint-todo.yml entries that no longer match any offense
       --exclude-limit N   Min files before grouping into pattern (default: 15)
 
 Information:

data/bin/yard-lint

@@ -18,7 +18,7 @@ begin
     config_file = file
   end
 
-  opts.on('-f', '--format FORMAT', 'Output format (text, json, quickfix)') do |format|
+  opts.on('-f', '--format FORMAT', 'Output format (text, json, quickfix, sarif)') do |format|
     options[:format] = format
   end
 
@@ -64,6 +64,10 @@ begin
     options[:only] = validators.split(',').map(&:strip)
   end
 
+  opts.on('--explain VALIDATOR', 'Explain what a validator checks and how to configure it') do |validator|
+    options[:explain] = validator
+  end
+
   opts.separator ''
   opts.separator 'Other options:'
 
@@ -95,6 +99,10 @@ begin
     options[:force] = true
   end
 
+  opts.on('--check-todo', 'Report .yard-lint-todo.yml entries that no longer match any offense') do
+    options[:check_todo] = true
+  end
+
   opts.on('--exclude-limit COUNT', Integer, 'Min files before grouping into pattern (default: 15)') do |count|
     options[:exclude_limit] = count
   end
@@ -112,17 +120,20 @@ begin
     puts '  yard-lint lib/                                 # Lint all files in lib/'
     puts '  yard-lint --only Tags/TypeSyntax lib/          # Run only one validator on lib/'
     puts '  yard-lint --only Tags/Order,Tags/TypeSyntax    # Run specific validators'
+    puts '  yard-lint --explain Tags/TypeSyntax            # Explain what a validator checks'
     puts '  yard-lint --diff main                          # Lint files changed since main branch'
     puts '  yard-lint --staged                             # Lint only staged files'
     puts '  yard-lint --changed                            # Lint only uncommitted files'
     puts '  yard-lint --format json lib/                   # Output in JSON format'
     puts '  yard-lint --format quickfix lib/               # Output in quickfix format (Vim/Emacs)'
+    puts '  yard-lint --format sarif lib/                  # Output SARIF 2.1.0 (GitHub code scanning)'
     puts '  yard-lint --init                               # Generate default config'
     puts '  yard-lint --init --strict                      # Generate strict config'
     puts '  yard-lint --update                             # Update config with new validators'
     puts '  yard-lint --auto-gen-config                    # Generate todo file for existing violations'
     puts '  yard-lint --regenerate-todo                    # Regenerate todo file'
     puts '  yard-lint --auto-gen-config --exclude-limit 10 # Custom grouping threshold'
+    puts '  yard-lint --check-todo                         # Fail if todo file has unused entries'
     puts '  cat lib/foo.rb | yard-lint --stdin lib/foo.rb  # Lint source piped from stdin'
     exit
   end
@@ -133,6 +144,62 @@ rescue OptionParser::ParseError => e
   exit 1
 end
 
+# Report one or more unknown validator names with "did you mean" suggestions,
+# the full list of available validators, and a pointer to --explain. Shared by
+# --only and --explain so the two stay consistent.
+report_unknown_validators = lambda do |names|
+  checker = DidYouMean::SpellChecker.new(dictionary: Yard::Lint::ConfigLoader::ALL_VALIDATORS)
+  messages = names.map do |name|
+    suggestions = checker.correct(name)
+    suggestions.any? ? "  #{name} (did you mean: #{suggestions.first}?)" : "  #{name}"
+  end
+  puts 'Error: Unknown validator(s):'
+  puts messages.join("\n")
+  puts "\nAvailable validators:"
+  Yard::Lint::ConfigLoader::ALL_VALIDATORS.each { |v| puts "  #{v}" }
+  puts "\nRun `yard-lint --explain VALIDATOR` to see what a validator checks."
+end
+
+# Apply --only filter if provided, exiting on unknown validator names
+apply_only = lambda do |config|
+  next unless options[:only]
+
+  unknown = options[:only] - Yard::Lint::ConfigLoader::ALL_VALIDATORS
+  if unknown.any?
+    report_unknown_validators.call(unknown)
+    exit 1
+  end
+  config.only_validators = options[:only]
+end
+
+# Load the config (-c file or auto-discovered), exiting with a configuration error
+# instead of a backtrace when it is missing, invalid or inherits in a cycle.
+# Shared by the normal run, --auto-gen-config and --check-todo.
+load_config = lambda do
+  if config_file
+    Yard::Lint::Config.from_file(config_file)
+  else
+    Yard::Lint::Config.load || Yard::Lint::Config.new
+  end
+rescue Yard::Lint::Errors::ConfigFileNotFoundError, Yard::Lint::Errors::CircularDependencyError => e
+  puts "Configuration Error: #{e.message}"
+  exit 1
+rescue Yard::Lint::Errors::InvalidConfigError => e
+  puts "Configuration Error:\n#{e.message}"
+  exit 1
+end
+
+# Handle --explain flag (early exit; needs no config or path)
+if options[:explain]
+  name = options[:explain]
+  unless Yard::Lint::ConfigLoader::ALL_VALIDATORS.include?(name)
+    report_unknown_validators.call([name])
+    exit 1
+  end
+  puts Yard::Lint::Explainer.call(name)
+  exit 0
+end
+
 # Disambiguate `--diff PATH`. `--diff [REF]` takes an optional argument, so
 # `yard-lint --diff lib/` makes OptionParser consume `lib/` as the REF, leaving
 # no PATH (the run then tries `git diff lib/...HEAD` and fails). When the --diff
@@ -189,12 +256,7 @@ end
 # Handle --auto-gen-config flag
 if options[:auto_gen_config]
   begin
-    # Load config
-    config = if config_file
-               Yard::Lint::Config.from_file(config_file)
-             else
-               Yard::Lint::Config.load || Yard::Lint::Config.new
-             end
+    config = load_config.call
 
     # Get path argument
     path = ARGV[0] || '.'
@@ -222,6 +284,26 @@ if options[:auto_gen_config]
   end
 end
 
+# Handle --check-todo flag
+if options[:check_todo]
+  begin
+    config = load_config.call
+    apply_only.call(config)
+
+    result = Yard::Lint::TodoGenerator.check(path: ARGV[0] || '.', config: config)
+
+    puts result[:message]
+    exit result[:unused_entries].empty? ? 0 : 1
+  rescue Yard::Lint::Errors::TodoFileNotFoundError, Yard::Lint::Errors::FileNotFoundError,
+         Yard::Lint::Git::Error => e
+    puts "Error: #{e.message}"
+    exit 1
+  rescue Yard::Lint::Errors::InvalidConfigError => e
+    puts "Configuration Error:\n#{e.message}"
+    exit 1
+  end
+end
+
 # Get path argument (defaults to current directory)
 path = ARGV[0] || '.'
 
@@ -239,51 +321,23 @@ end
 YARD::Registry.clear
 
 # Load config and apply CLI overrides
-begin
-  config = if config_file
-             Yard::Lint::Config.from_file(config_file)
-           else
-             Yard::Lint::Config.load || Yard::Lint::Config.new
-           end
-rescue Yard::Lint::Errors::ConfigFileNotFoundError => e
-  puts "Configuration Error: #{e.message}"
-  exit 1
-rescue Yard::Lint::Errors::InvalidConfigError => e
-  puts "Configuration Error:\n#{e.message}"
-  exit 1
-end
+config = load_config.call
 
 # Apply CLI min_coverage override if provided
 config.min_coverage = options[:min_coverage] if options[:min_coverage]
 
-# Apply --only filter if provided
-if options[:only]
-  unknown = options[:only] - Yard::Lint::ConfigLoader::ALL_VALIDATORS
-  if unknown.any?
-    checker = DidYouMean::SpellChecker.new(dictionary: Yard::Lint::ConfigLoader::ALL_VALIDATORS)
-    messages = unknown.map do |name|
-      suggestions = checker.correct(name)
-      suggestions.any? ? "  #{name} (did you mean: #{suggestions.first}?)" : "  #{name}"
-    end
-    puts "Error: Unknown validator(s):"
-    puts messages.join("\n")
-    puts "\nAvailable validators:"
-    Yard::Lint::ConfigLoader::ALL_VALIDATORS.each { |v| puts "  #{v}" }
-    exit 1
-  end
-  config.only_validators = options[:only]
-end
+apply_only.call(config)
 
 # Validate the output format before doing any (potentially long) work, rather
 # than running the whole lint and only then rejecting an unknown format.
-valid_formats = %w[text json quickfix]
+valid_formats = %w[text json quickfix sarif]
 if options[:format] && !valid_formats.include?(options[:format])
   puts "Error: Unknown format '#{options[:format]}'. Valid formats: #{valid_formats.join(', ')}"
   exit 1
 end
 
-# Suppress progress for quickfix to avoid contaminating machine-readable output
-options[:progress] = false if options[:format] == 'quickfix' && options[:progress].nil?
+# Suppress progress for machine-readable formats to avoid contaminating output
+options[:progress] = false if %w[quickfix sarif].include?(options[:format]) && options[:progress].nil?
 
 # Run the linter
 begin
@@ -332,6 +386,12 @@ when 'quickfix'
     puts "#{offense[:location]}:#{offense[:location_line]}: #{char}: #{offense[:validator]}: #{message}"
   end
   exit result.exit_code
+when 'sarif'
+  # Base paths on the repository root so GitHub can map offense URIs onto files
+  # even when yard-lint is run from a subdirectory.
+  sarif = Yard::Lint::Formatters::Sarif.new(result.offenses, base_dir: Yard::Lint::Git.repository_root)
+  puts sarif.generate
+  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

data/lib/yard/lint/config.rb

@@ -6,6 +6,7 @@ module Yard
     class Config
       attr_reader :raw_config, :validators
       attr_accessor :only_validators
+      attr_writer :base_dir
 
       # Default YAML config file name
       DEFAULT_CONFIG_FILE = '.yard-lint.yml'
@@ -16,6 +17,9 @@ module Yard
       # Metadata keys to skip when merging validator configs
       METADATA_KEYS = %w[Description StyleGuide VersionAdded VersionChanged].freeze
 
+      # File.fnmatch flags used for Exclude patterns
+      EXCLUDE_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
       # @param raw_config [Hash] raw configuration hash (new hierarchical format)
       def initialize(raw_config = {})
         @raw_config = raw_config
@@ -42,7 +46,7 @@ module Yard
           # Load with inheritance support
           merged_yaml = ConfigLoader.load(path)
 
-          new(merged_yaml)
+          new(merged_yaml) { |config| config.base_dir = File.dirname(File.expand_path(path)) }
         end
 
         # Search for and load config file from current directory upwards
@@ -173,29 +177,101 @@ module Yard
       end
 
       # Get validator severity
+      #
+      # Resolution order (highest priority first):
+      #   1. an explicit per-validator Severity in the user's config
+      #   2. a category-level Severity (e.g. `Documentation: { Severity: convention }`),
+      #      matching how category-level Enabled cascades in #validator_enabled?
+      #   3. the validator's built-in default Severity
+      #   4. the global 'warning' default
+      #
       # @param validator_name [String] full validator name
       # @return [String] severity level for this validator
       def validator_severity(validator_name)
+        # An explicit per-validator Severity in the user's config wins.
+        raw_validator = @raw_config[validator_name]
+        if raw_validator.is_a?(Hash) && raw_validator['Severity']
+          return raw_validator['Severity'].to_s
+        end
+
+        # Otherwise honor a category-level Severity, which previously validated
+        # but was ignored (the category-level Enabled key already cascades).
+        category = validator_name.split('/').first
+        raw_category = @raw_config[category]
+        if raw_category.is_a?(Hash) && raw_category['Severity']
+          return raw_category['Severity'].to_s
+        end
+
+        # Fall back to the validator's built-in default, then the global default.
         validator_config = validators[validator_name] || {}
         validator_config['Severity'] || 'warning'
       end
 
       # Get validator-specific exclude patterns
+      #
+      # A category-level Exclude (e.g. `Documentation: { Exclude: [...] }`) is
+      # unioned with the per-validator one rather than replaced by it, so a
+      # validator that sets its own Exclude still skips its category's files.
+      #
       # @param validator_name [String] full validator name
-      # @return [Array<String>] exclusion patterns for this validator
+      # @return [Array<String>] exclusion patterns for this validator (category + per-validator)
       def validator_exclude(validator_name)
         validator_config = validators[validator_name] || {}
-        validator_config['Exclude'] || []
+        raw_category = @raw_config[validator_name.split('/').first]
+        category_exclude = raw_category.is_a?(Hash) ? Array(raw_category['Exclude']) : []
+
+        (category_exclude + (validator_config['Exclude'] || [])).uniq
       end
 
-      # Combined global and per-validator exclusions
+      # Combined global, category 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)
+      # @return [Array<String>] combined exclusion patterns (global + category + per-validator)
       def validator_all_excludes(validator_name)
         exclude + validator_exclude(validator_name)
       end
 
+      # Directory that Exclude patterns are relative to
+      # @return [String] directory of the loaded config file, or the current directory without one
+      def base_dir
+        @base_dir || Dir.pwd
+      end
+
+      # Whether a file matches any of the given Exclude patterns
+      # A pattern matches the path relative to {#base_dir} or the absolute path
+      # @param file [String] absolute file path, or one relative to the current directory
+      # @param patterns [Array<String>] glob patterns
+      # @return [Boolean] true if any pattern matches
+      def excluded_path?(file, patterns)
+        absolute = File.expand_path(file)
+        relative = relative_path(absolute)
+
+        patterns.any? do |pattern|
+          File.fnmatch(pattern, relative, EXCLUDE_FLAGS) || File.fnmatch(pattern, absolute, EXCLUDE_FLAGS)
+        end
+      end
+
+      # Path of a file relative to {#base_dir}
+      # Symlinks are resolved when the plain paths do not nest (/var is /private/var on macOS)
+      # @param file [String] absolute file path, or one relative to the current directory
+      # @return [String] relative path (with ../ for a file outside {#base_dir}), or the absolute
+      #   path when there is no relative one (another drive)
+      def relative_path(file)
+        absolute = File.expand_path(file)
+        base = File.expand_path(base_dir)
+        return absolute.delete_prefix("#{base}/") if absolute.start_with?("#{base}/")
+
+        from, to = begin
+          [File.realpath(absolute), File.realpath(base)]
+        rescue SystemCallError
+          [absolute, base]
+        end
+
+        Pathname.new(from).relative_path_from(Pathname.new(to)).to_s
+      rescue ArgumentError
+        absolute
+      end
+
       # Get validator-specific configuration value
       # @param validator_name [String] full validator name
       # @param key [String] configuration key