yard-lint 1.11.0 → 1.13.0

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Contracts
+      # Validates the whole configuration: root keys, AllValidators, categories and validators
+      class Config < Base
+        # Valid category names (from ConfigUpdater::CATEGORY_ORDER)
+        VALID_CATEGORIES = %w[Documentation Tags Warnings Semantic].freeze
+
+        # Keys that are valid at the root level but are not validators
+        SPECIAL_KEYS = %w[
+          AllValidators
+          inherit_from
+          inherit_gem
+        ].freeze
+
+        # Validator names must contain a '/' (category/name format)
+        virtual do |data|
+          data.keys.filter_map do |key|
+            next if SPECIAL_KEYS.include?(key)
+            next if VALID_CATEGORIES.include?(key)
+            next if key.include?('/')
+
+            [[key], message("Unknown validator: '#{key}'", suggest_validator_name(key))]
+          end
+        end
+
+        optional('AllValidators') do |all_validators|
+          !all_validators || all_validators.is_a?(Hash) ||
+            "Invalid AllValidators: must be a Hash, got #{all_validators.class}"
+        end
+
+        # Only specific known settings are validated, unknown keys pass through
+        # This allows users to put custom data in AllValidators
+        nested('AllValidators') do
+          optional('FailOnSeverity') do |fail_on|
+            !fail_on || Lint::Config::VALID_SEVERITIES.include?(fail_on.to_s) ||
+              message("Invalid FailOnSeverity: '#{fail_on}'", "  Valid values: #{Lint::Config::VALID_SEVERITIES.join(', ')}")
+          end
+
+          optional('MinCoverage') do |min_cov|
+            !min_cov || (min_cov.is_a?(Numeric) && !(min_cov < 0 || min_cov > 100)) ||
+              message("Invalid MinCoverage: '#{min_cov}'", '  Must be a number between 0 and 100')
+          end
+
+          optional('Exclude') do |exclude|
+            !exclude || exclude.is_a?(Array) ||
+              "Invalid Exclude in AllValidators: must be an array, got #{exclude.class}"
+          end
+
+          optional('YardOptions') do |yard_options|
+            !yard_options || yard_options.is_a?(Array) ||
+              "Invalid YardOptions in AllValidators: must be an array, got #{yard_options.class}"
+          end
+        end
+
+        virtual do |data|
+          data.flat_map do |key, value|
+            next [] unless VALID_CATEGORIES.include?(key)
+            next [] unless value.is_a?(Hash)
+
+            nested_errors(Category.new(key).call(value, scope: [key]))
+          end
+        end
+
+        virtual do |data|
+          data.flat_map do |key, value|
+            next [] unless key.include?('/')
+
+            unless value.is_a?(Hash)
+              next [[[key], "Invalid configuration for validator '#{key}': expected a Hash, got #{value.class}"]]
+            end
+
+            nested_errors(Validator.new(key).call(value, scope: [key]))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/contracts/validator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Contracts
+      # Validates a single validator configuration (e.g. `Tags/Order: { Enabled: ... }`)
+      class Validator < Base
+        # Base config keys that are valid for all validators
+        BASE_KEYS = %w[Enabled Severity Exclude YardOptions].freeze
+
+        # @return [String] validator name
+        attr_reader :name
+
+        # @param name [String] validator name used in error messages
+        def initialize(name)
+          super()
+          @name = name
+        end
+
+        virtual do |_data, _errors, contract|
+          next if ConfigLoader::ALL_VALIDATORS.include?(contract.name)
+
+          [[[], message("Unknown validator: '#{contract.name}'", suggest_validator_name(contract.name))]]
+        end
+
+        optional('Enabled') do |enabled, _data, _errors, contract|
+          !enabled || BOOLEAN_VALUES.include?(enabled) ||
+            message("Invalid Enabled value for #{contract.name}: '#{enabled}'", '  Must be true or false')
+        end
+
+        optional('Severity') do |severity, _data, _errors, contract|
+          !severity || Lint::Config::VALID_SEVERITIES.include?(severity.to_s) ||
+            message(
+              "Invalid Severity for #{contract.name}: '#{severity}'",
+              "  Valid values: #{Lint::Config::VALID_SEVERITIES.join(', ')}",
+              suggest_similar_severity(severity.to_s)
+            )
+        end
+
+        optional('Exclude') do |exclude, _data, _errors, contract|
+          !exclude || exclude.is_a?(Array) ||
+            "Invalid Exclude for #{contract.name}: must be an array, got #{exclude.class}"
+        end
+
+        optional('YardOptions') do |yard_options, _data, _errors, contract|
+          !yard_options || yard_options.is_a?(Array) ||
+            "Invalid YardOptions for #{contract.name}: must be an array, got #{yard_options.class}"
+        end
+
+        # Unknown validator-specific keys (an unknown validator is already reported)
+        virtual do |data, _errors, contract|
+          next unless ConfigLoader::ALL_VALIDATORS.include?(contract.name)
+
+          validator_config_class = ConfigLoader.validator_config(contract.name)
+          next unless validator_config_class
+
+          valid_keys = (validator_config_class.defaults.keys + Lint::Config::METADATA_KEYS + BASE_KEYS).uniq.sort
+
+          (data.keys - valid_keys).map do |key|
+            [
+              [key],
+              message(
+                "Unknown configuration key for #{contract.name}: '#{key}'",
+                "  Valid keys: #{valid_keys.join(', ')}"
+              )
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/errors.rb

@@ -22,6 +22,9 @@ module Yard
       # Raised when .yard-lint-todo.yml already exists without force flag
       class TodoFileExistsError < BaseError; end
 
+      # Raised when .yard-lint-todo.yml is required but does not exist
+      class TodoFileNotFoundError < BaseError; end
+
       # Raised when configuration is invalid
       class InvalidConfigError < BaseError; end
     end

data/lib/yard/lint/executor/in_process_registry.rb

@@ -112,7 +112,7 @@ module Yard
               next false unless obj.file
 
               file_excludes.any? do |pattern|
-                File.fnmatch(pattern, obj.file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+                File.fnmatch(pattern, obj.file, Config::EXCLUDE_FLAGS)
               end
             end
           end

data/lib/yard/lint/explainer.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Renders a human-readable explanation of a single validator for the terminal.
+    #
+    # The explanation is sourced from the validator's own YARD documentation block
+    # (the module file, e.g. `validators/tags/type_syntax.rb`) - yard-lint reads its
+    # own YARD docs to explain itself. This keeps the explanation next to the code it
+    # documents rather than in a separate file that can drift, and gives the doc
+    # blocks a standing reason to stay accurate.
+    #
+    # @example
+    #   puts Yard::Lint::Explainer.call("Tags/TypeSyntax")
+    class Explainer
+      # Keys in a validator's defaults that are surfaced in the header rather than
+      # listed as tunable configuration options.
+      META_KEYS = %w[Enabled Severity].freeze
+
+      # Build the explanation for a validator.
+      # @param name [String] validator name (e.g. 'Tags/TypeSyntax')
+      # @return [String] formatted, terminal-ready explanation
+      def self.call(name)
+        new(name).call
+      end
+
+      # Structured description of a validator for programmatic consumers such as
+      # the SARIF formatter's rule metadata (as opposed to #call's terminal text).
+      # @param name [String] validator name (e.g. 'Tags/TypeSyntax')
+      # @return [Hash{Symbol => String}, nil] { short:, full: }, or nil when the
+      #   name is unknown or the validator has no docstring
+      def self.describe(name)
+        new(name).describe
+      end
+
+      # @param name [String] validator name (e.g. 'Tags/TypeSyntax')
+      def initialize(name)
+        @name = name
+      end
+
+      # @return [Hash{Symbol => String}, nil] { short:, full: } description of the
+      #   validator, or nil when unknown or undocumented
+      def describe
+        return nil unless ConfigLoader::ALL_VALIDATORS.include?(@name)
+
+        doc = documentation
+        return nil unless doc
+
+        full = prose_only(doc[:description])
+        return nil if full.empty?
+
+        { short: first_sentence(full), full: full }
+      end
+
+      # @return [String] formatted, terminal-ready explanation
+      # @raise [ArgumentError] if name is not a known validator
+      def call
+        unless ConfigLoader::ALL_VALIDATORS.include?(@name)
+          raise ArgumentError, "Unknown validator: #{@name.inspect}"
+        end
+
+        [header, body].compact.join("\n")
+      end
+
+      private
+
+      # @return [String] the metadata header (name, defaults) for the validator
+      def header
+        lines = [@name.to_s]
+        lines << "  Enabled by default: #{default_config.validator_enabled?(@name)}"
+        lines << "  Default severity:   #{default_config.validator_severity(@name)}"
+
+        config_keys = validator_defaults.keys - META_KEYS
+        lines << "  Configuration keys: #{config_keys.join(', ')}" if config_keys.any?
+        lines.join("\n")
+      end
+
+      # @return [String] the documentation body (description, config, examples)
+      def body
+        doc = documentation
+        return raw_comment_fallback if doc.nil?
+
+        sections = ["\n#{doc[:description]}"]
+        sections << render_examples(doc[:examples]) if doc[:examples].any?
+        sections.join("\n")
+      end
+
+      # @param examples [Array(String, String)] pairs of example label and code
+      # @return [String] the rendered "Examples:" section
+      def render_examples(examples)
+        rendered = examples.map do |name, text|
+          code = text.each_line.map { |line| "    #{line}" }.join
+          "  #{name}\n#{code}".rstrip
+        end
+        "\nExamples:\n#{rendered.join("\n\n")}"
+      end
+
+      # A config carrying only built-in defaults (no user overrides), used as the
+      # authoritative source for the validator's default enabled state and
+      # severity so the header never drifts from how the linter actually resolves
+      # them (see Config#validator_enabled? / #validator_severity).
+      # @return [Config] the defaults-only config
+      def default_config
+        @default_config ||= Config.new
+      end
+
+      # @return [Hash] the validator's default configuration
+      def validator_defaults
+        config = ConfigLoader.validator_config(@name)
+        config&.defaults || {}
+      end
+
+      # Parse the validator's module file with YARD and extract its description
+      # and examples. Runs in an isolated registry - any objects a caller parsed
+      # before us are saved and restored - so explaining a validator never
+      # clobbers the shared YARD::Registry.
+      # @return [Hash, nil] { description: String, examples: Array((String, String)) }
+      #   or nil if no docstring is available
+      def documentation
+        path = source_path
+        return nil unless path && File.exist?(path)
+
+        saved = YARD::Registry.all
+        YARD::Registry.clear
+        begin
+          YARD.parse_string(File.read(path))
+          docstring = YARD::Registry.at(object_path)&.docstring
+          return nil if docstring.nil? || docstring.to_s.strip.empty?
+
+          {
+            description: docstring.to_s,
+            examples: docstring.tags(:example).map { |tag| [tag.name, tag.text.to_s] }
+          }
+        ensure
+          YARD::Registry.clear
+          saved.each { |object| YARD::Registry.register(object) }
+        end
+      end
+
+      # The human description of a validator: its docstring prose with the leading
+      # "<Name> validator" title line and any trailing "## ..." sections (e.g.
+      # Configuration) removed, leaving just the explanation.
+      # @param description [String] the raw docstring text
+      # @return [String] the trimmed prose (may be empty)
+      def prose_only(description)
+        lines = description.to_s.lines.take_while { |line| !line.start_with?('## ') }
+        text = lines.join
+        text = text.sub(/\A.*validator[ \t]*\n+/i, '') if text.match?(/\A.*validator[ \t]*\n/i)
+        text.strip
+      end
+
+      # @param text [String] prose text
+      # @return [String] the first sentence, for a concise one-line summary
+      def first_sentence(text)
+        flat = text.tr("\n", ' ').squeeze(' ').strip
+        flat[/.*?[.!?](?=\s|\z)/] || flat
+      end
+
+      # @return [String] the fully-qualified code object path (e.g.
+      #   'Yard::Lint::Validators::Tags::TypeSyntax')
+      def object_path
+        category, validator = @name.split('/')
+        "Yard::Lint::Validators::#{category}::#{validator}"
+      end
+
+      # Resolve the validator module file from its name by inverting the casing
+      # convention used in ConfigLoader.discover_validators.
+      # @return [String] absolute path to the validator module file
+      def source_path
+        category, validator = @name.split('/')
+        File.join(__dir__, 'validators', snake_case(category), "#{snake_case(validator)}.rb")
+      end
+
+      # Convert a PascalCase segment to snake_case (inverse of the
+      # `split('_').map(&:capitalize).join` used during discovery).
+      # @param string [String] PascalCase name (e.g. 'TypeSyntax')
+      # @return [String] snake_case name (e.g. 'type_syntax')
+      def snake_case(string)
+        string.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+
+      # Defensive fallback: print the raw leading comment block from the module
+      # file when YARD yields no docstring. Every validator currently ships a doc
+      # block, so this should not normally be reached.
+      # @return [String, nil] the raw comment text, or nil if it cannot be read
+      def raw_comment_fallback
+        path = source_path
+        return nil unless path && File.exist?(path)
+
+        comment = []
+        File.foreach(path) do |line|
+          stripped = line.strip
+          if stripped.start_with?('#')
+            comment << stripped.sub(/\A#\s?/, '')
+          elsif stripped.start_with?('module ') && comment.any?
+            break
+          else
+            comment.clear
+          end
+        end
+        comment.any? ? "\n#{comment.join("\n")}" : nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'pathname'
+require 'digest'
+
+module Yard
+  module Lint
+    module Formatters
+      # Renders lint results as SARIF 2.1.0 (Static Analysis Results Interchange
+      # Format) - the JSON format GitHub code scanning and other result aggregators
+      # ingest, so yard-lint offenses can surface as PR annotations / Security-tab
+      # alerts instead of being buried in CI logs.
+      #
+      # This is output only: it does not change which offenses are reported, the
+      # exit code, or any configuration - it is an alternative rendering of the
+      # same result. Rule metadata (`rules[]`) is populated from each validator's
+      # own YARD documentation via {Explainer.describe}.
+      class Sarif
+        # SARIF 2.1.0 JSON schema URI, emitted as the document's `$schema`.
+        # @return [String]
+        SCHEMA_URI = 'https://json.schemastore.org/sarif-2.1.0.json'
+
+        # Tool information URI, emitted as the driver's `informationUri`.
+        # @return [String]
+        INFORMATION_URI = 'https://github.com/mensfeld/yard-lint'
+
+        # Help URI for each rule (the wiki validator reference).
+        # @return [String]
+        HELP_URI = 'https://github.com/mensfeld/yard-lint/wiki/Validators'
+
+        # SARIF supports only error/warning/note (plus none). yard-lint's
+        # `convention` maps to note, and `never` (report-only) maps to none.
+        # @return [Hash{String => String}]
+        SEVERITY_LEVELS = {
+          'error' => 'error',
+          'warning' => 'warning',
+          'convention' => 'note',
+          'never' => 'none'
+        }.freeze
+
+        # Fallback SARIF level for any unrecognized severity.
+        # @return [String]
+        DEFAULT_LEVEL = 'warning'
+
+        # partialFingerprints key, versioned so the scheme can evolve without
+        # invalidating history. GitHub uses it to correlate results across runs.
+        # @return [String]
+        FINGERPRINT_KEY = 'yardLintOffense/v1'
+
+        # @param offenses [Array<Hash>] offense hashes (from `result.offenses`)
+        # @param base_dir [String] directory that offense paths are made relative
+        #   to, so GitHub can map them onto the repository (default: current dir)
+        def initialize(offenses, base_dir: Dir.pwd)
+          @offenses = offenses
+          @base_dir = base_dir
+        end
+
+        # @return [String] pretty-printed SARIF 2.1.0 JSON
+        def generate
+          JSON.pretty_generate(document)
+        end
+
+        # @return [Hash] the SARIF document as a Ruby hash
+        def document
+          rule_ids = @offenses.map { |offense| offense[:validator] }.compact.uniq
+          rule_index = rule_ids.each_with_index.to_h
+
+          {
+            '$schema' => SCHEMA_URI,
+            'version' => '2.1.0',
+            'runs' => [
+              {
+                'tool' => { 'driver' => driver(rule_ids) },
+                'results' => @offenses.map { |offense| result(offense, rule_index) }
+              }
+            ]
+          }
+        end
+
+        private
+
+        # @param rule_ids [Array<String>] distinct validator names, in result order
+        # @return [Hash] the SARIF tool driver, including rule metadata
+        def driver(rule_ids)
+          {
+            'name' => 'yard-lint',
+            'informationUri' => INFORMATION_URI,
+            'version' => Yard::Lint::VERSION,
+            'rules' => rule_ids.map { |id| rule(id) }
+          }
+        end
+
+        # @param id [String] validator name (e.g. 'Tags/TypeSyntax')
+        # @return [Hash] a SARIF reportingDescriptor for the validator
+        def rule(id)
+          entry = {
+            'id' => id,
+            'name' => id.split('/').last,
+            'helpUri' => HELP_URI,
+            'defaultConfiguration' => { 'level' => level(default_severity(id)) }
+          }
+
+          described = Explainer.describe(id)
+          if described
+            entry['shortDescription'] = { 'text' => described[:short] }
+            entry['fullDescription'] = { 'text' => described[:full] }
+          end
+
+          entry
+        end
+
+        # @param offense [Hash] an offense hash
+        # @param rule_index [Hash{String => Integer}] validator name to rule index
+        # @return [Hash] a SARIF result
+        def result(offense, rule_index)
+          uri = relative_uri(offense[:location])
+          entry = {}
+
+          # ruleId/ruleIndex are optional in SARIF; omit them (rather than emit
+          # null, which is schema-invalid) for the rare offense with no validator.
+          validator = offense[:validator]
+          if validator
+            entry['ruleId'] = validator
+            entry['ruleIndex'] = rule_index[validator]
+          end
+
+          entry['level'] = level(offense[:severity])
+          entry['message'] = { 'text' => offense[:message].to_s }
+          entry['locations'] = [location(offense, uri)]
+          entry['partialFingerprints'] = { FINGERPRINT_KEY => fingerprint(offense, uri) }
+          entry
+        end
+
+        # @param offense [Hash] an offense hash
+        # @param uri [String] the artifact URI (already made relative)
+        # @return [Hash] a SARIF location
+        def location(offense, uri)
+          {
+            'physicalLocation' => {
+              'artifactLocation' => { 'uri' => uri },
+              'region' => { 'startLine' => start_line(offense) }
+            }
+          }
+        end
+
+        # A line-independent fingerprint so GitHub correlates the same offense
+        # across commits without churn (close/reopen) when unrelated lines shift.
+        # Keys on the validator, file, and offending object, excluding the line
+        # number and (when an object is identified) the message, so a re-worded
+        # message does not churn alerts. Validators that do not identify an object
+        # fall back to a normalized message, so distinct offenses in one file
+        # still get distinct fingerprints instead of collapsing into one alert.
+        # @param offense [Hash] an offense hash
+        # @param uri [String] the artifact URI (already made relative)
+        # @return [String] a stable hex digest
+        def fingerprint(offense, uri)
+          element = offense[:element].to_s
+          # Tag the identity with its source so an element that happens to equal
+          # another offense's normalized message cannot collide.
+          identity = element.empty? ? "m:#{normalized_message(offense[:message])}" : "e:#{element}"
+          parts = [offense[:validator], uri, identity]
+          Digest::SHA256.hexdigest(parts.map(&:to_s).join("\x00"))
+        end
+
+        # Message reduced to a stable identity for offenses with no :element:
+        # whitespace is collapsed so trivial formatting differences do not churn
+        # alerts. Case is preserved - messages embed case-sensitive names (types,
+        # methods, constants), so downcasing could merge genuinely distinct offenses.
+        # @param message [String, nil] the offense message
+        # @return [String] the normalized message
+        def normalized_message(message)
+          message.to_s.gsub(/\s+/, ' ').strip
+        end
+
+        # @param severity [String, nil] a yard-lint severity
+        # @return [String] the SARIF level
+        def level(severity)
+          SEVERITY_LEVELS.fetch(severity.to_s, DEFAULT_LEVEL)
+        end
+
+        # SARIF regions are 1-based; guard against a missing or zero line.
+        # @param offense [Hash] an offense hash
+        # @return [Integer] a 1-based start line
+        def start_line(offense)
+          line = (offense[:location_line] || offense[:line]).to_i
+          line.positive? ? line : 1
+        end
+
+        # Make a path repository-relative so GitHub maps it onto a file. Paths
+        # already relative are kept; a path outside base_dir keeps its original
+        # value rather than emitting a `../` or absolute URI.
+        # @param location [String, nil] the offense location path
+        # @return [String] a relative URI where possible
+        def relative_uri(location)
+          path = location.to_s
+          return path if path.empty?
+
+          absolute = File.absolute_path(path, @base_dir)
+          relative = Pathname.new(absolute).relative_path_from(Pathname.new(@base_dir)).to_s
+          relative.start_with?('..') ? path : relative
+        rescue ArgumentError
+          # relative_path_from raises across platforms/mixed roots; fall back.
+          path
+        end
+
+        # The validator's default severity, from a defaults-only config, for the
+        # rule's defaultConfiguration.level.
+        # @param id [String] validator name
+        # @return [String] default severity
+        def default_severity(id)
+          @default_config ||= Config.new
+          @default_config.validator_severity(id)
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/git.rb

@@ -89,15 +89,17 @@ module Yard
           filter_ruby_files(files.uniq, path)
         end
 
-        private
-
-        # Absolute path to the repository root (git reports paths relative to it)
+        # Absolute path to the repository root (git reports paths relative to it).
+        # Used to make report paths repository-relative; falls back to the current
+        # directory outside a git repo.
         # @return [String] repo root, or the current directory if it can't be determined
         def repository_root
           stdout, _stderr, status = Open3.capture3('git', 'rev-parse', '--show-toplevel')
           status.success? ? stdout.strip : Dir.pwd
         end
 
+        private
+
         # Ensure we're in a git repository
         # @raise [Error] if not in a git repository
         def ensure_git_repository!

data/lib/yard/lint/result_builder.rb

@@ -22,8 +22,7 @@ module Yard
         validator_cfg = ConfigLoader.validator_config(validator_name)
         return nil unless validator_module && validator_cfg
 
-        # Skip if this validator is a child of a composite
-        return nil if composite_child?(validator_name)
+        return nil if reported_by_composite?(validator_name)
 
         # Handle composite validators (those that combine multiple validators)
         unless validator_cfg.combines_with.empty?
@@ -36,15 +35,17 @@ module Yard
 
       private
 
-      # Check if a validator is a child of a composite validator
+      # Check if a composite parent reports this validator's offenses
+      # A child reports on its own only when --only selects it without its parent
       # @param validator_name [String] validator name to check
-      # @return [Boolean] true if this is a composite child
-      def composite_child?(validator_name)
+      # @return [Boolean] true if a composite parent reports it
+      def reported_by_composite?(validator_name)
         ConfigLoader::ALL_VALIDATORS.any? do |parent_name|
           parent_cfg = ConfigLoader.validator_config(parent_name)
           next unless parent_cfg
+          next unless parent_cfg.combines_with.include?(validator_name)
 
-          parent_cfg.combines_with.include?(validator_name)
+          config.only_validators.empty? || config.only_validators.include?(parent_name)
         end
       end