yard-lint 1.2.3 → 1.3.0.rc1

data/lib/yard/lint/validators/tags/example_syntax/validator.rb

@@ -7,78 +7,65 @@ module Yard
         module ExampleSyntax
           # Validator to check syntax of code in @example tags
           class Validator < Base
-            private
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
 
-            # Runs yard list query to find objects with invalid syntax in @example tags
-            # @param dir [String] dir where the yard db is (or where it should be generated)
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, file_list_path)
-              cmd = <<~CMD
-                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
-                --private \
-                --protected \
-                -b #{Shellwords.escape(dir)}
-              CMD
-              cmd = cmd.tr("\n", ' ')
-              cmd = cmd.gsub('yard list', "yard list --query #{query}")
+            # Execute query for a single object during in-process execution.
+            # Checks syntax of code in @example tags.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              return unless object.has_tag?(:example)
 
-              shell(cmd)
-            end
-
-            # @return [String] yard query to find @example tags with syntax errors
-            def query
-              <<~QUERY
-                '
-                  if object.has_tag?(:example)
-                    example_tags = object.tags(:example)
+              example_tags = object.tags(:example)
 
-                    example_tags.each_with_index do |example, index|
-                      code = example.text
-                      next if code.nil? || code.empty?
+              example_tags.each_with_index do |example, index|
+                code = example.text
+                next if code.nil? || code.empty?
 
-                      # Clean the code: strip output indicators (#=>) and everything after it
-                      code_lines = code.split("\\n").map do |line|
-                        line.sub(/\\s*#\\s*=>.*$/, "")
-                      end
+                # Clean the code: strip output indicators (#=>) and everything after it
+                code_lines = code.split("\n").map do |line|
+                  line.sub(/\s*#\s*=>.*$/, '')
+                end
 
-                      cleaned_code = code_lines.join("\\n").strip
-                      next if cleaned_code.empty?
+                cleaned_code = code_lines.join("\n").strip
+                next if cleaned_code.empty?
 
-                      # Check if code looks incomplete (single expression without context)
-                      # Skip validation for these cases
-                      lines = cleaned_code.split("\\n").reject { |l| l.strip.empty? || l.strip.start_with?("#") }
+                # Check if code looks incomplete (single expression without context)
+                lines = cleaned_code.split("\n").reject { |l| l.strip.empty? || l.strip.start_with?('#') }
 
-                      # Skip if it is a single line that looks like an incomplete expression
-                      if lines.size == 1
-                        line = lines.first.strip
-                        # Skip method calls, variable references, or simple expressions
-                        # These are likely incomplete snippets showing usage
-                        if line.match?(/^[a-z_][a-z0-9_]*(\\.| |$)/) || line.match?(/^[A-Z]/) && !line.match?(/^(class|module|def)\\s/)
-                          next
-                        end
-                      end
+                # Skip if it is a single line that looks like an incomplete expression
+                if lines.size == 1
+                  line = lines.first.strip
+                  # Skip method calls, variable references, or simple expressions
+                  next if line.match?(/^[a-z_][a-z0-9_]*(\.| |$)/) ||
+                          (line.match?(/^[A-Z]/) && !line.match?(/^(class|module|def)\s/))
+                end
 
-                      # Try to parse the code
-                      begin
-                        RubyVM::InstructionSequence.compile(cleaned_code)
-                      rescue SyntaxError => e
-                        # Report syntax errors
-                        example_name = example.name || "Example " + (index + 1).to_s
-                        puts object.file + ":" + object.line.to_s + ": " + object.title
-                        puts "syntax_error"
-                        puts example_name
-                        puts e.message
-                      rescue => e
-                        # Other errors (like NameError, ArgumentError) are fine
-                        # We only check syntax, not semantics
-                        next
-                      end
-                    end
-                  end
-                  false
-                '
-              QUERY
+                # Try to parse the code
+                # Suppress Ruby parser warnings (like "... at EOL, should be parenthesized?")
+                # that can occur during compilation of valid but stylistically questionable code
+                original_verbose = $VERBOSE
+                begin
+                  $VERBOSE = nil
+                  RubyVM::InstructionSequence.compile(cleaned_code)
+                rescue SyntaxError => e
+                  example_name = example.name || "Example #{index + 1}"
+                  collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                  collector.puts 'syntax_error'
+                  collector.puts example_name
+                  collector.puts e.message
+                rescue ScriptError, EncodingError => e
+                  # Non-syntax script errors (LoadError, NotImplementedError) and encoding
+                  # issues should be logged but not reported as syntax errors.
+                  # We only validate syntax, not runtime semantics or encoding validity.
+                  warn "[YARD::Lint] Example code error in #{object.path}: #{e.class}: #{e.message}" if ENV['DEBUG']
+                  next
+                ensure
+                  $VERBOSE = original_verbose
+                end
+              end
             end
           end
         end

data/lib/yard/lint/validators/tags/example_syntax.rb

@@ -33,7 +33,6 @@ module Yard
         #
         #     Tags/ExampleSyntax:
         #       Enabled: false
-        #
         module ExampleSyntax
         end
       end

data/lib/yard/lint/validators/tags/informal_notation/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InformalNotation
+          # Configuration for InformalNotation validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :informal_notation
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning',
+              'CaseSensitive' => false,
+              'RequireStartOfLine' => true,
+              'Patterns' => {
+                'Note' => '@note',
+                'IMPORTANT' => '@note',
+                'Important' => '@note',
+                'Todo' => '@todo',
+                'TODO' => '@todo',
+                'FIXME' => '@todo',
+                'See' => '@see',
+                'See also' => '@see',
+                'Warning' => '@deprecated',
+                'Deprecated' => '@deprecated',
+                'Author' => '@author',
+                'Version' => '@version',
+                'Since' => '@since',
+                'Returns' => '@return',
+                'Raises' => '@raise',
+                'Example' => '@example'
+              }
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/informal_notation/messages_builder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InformalNotation
+          # Builds human-readable messages for InformalNotation violations
+          class MessagesBuilder
+            class << self
+              # Formats an informal notation violation message
+              # @param offense [Hash] offense details with :pattern, :replacement, :line_text keys
+              # @return [String] formatted message
+              def call(offense)
+                pattern = offense[:pattern]
+                replacement = offense[:replacement]
+                line_text = offense[:line_text]
+
+                message = "Use #{replacement} tag instead of '#{pattern}:' notation"
+
+                if line_text && !line_text.empty?
+                  # Truncate long lines for readability
+                  truncated = line_text.length > 60 ? "#{line_text[0..57]}..." : line_text
+                  message += ". Found: \"#{truncated}\""
+                end
+
+                message
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/informal_notation/parser.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InformalNotation
+          # Parser for InformalNotation validator output
+          # Parses YARD query output that reports informal notation violations
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses YARD output and extracts informal notation violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ObjectName
+            #   pattern|replacement|line_offset|line_text
+            # @param yard_output [String] raw YARD query results
+            # @option _kwargs [Object] :unused this parameter accepts no options (reserved for future use)
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **_kwargs)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+              violations = []
+
+              lines.each_slice(2) do |location_line, details_line|
+                next unless location_line && details_line
+
+                # Parse location: "file.rb:10: ObjectName"
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # Parse details: "pattern|replacement|line_offset|line_text"
+                details = details_line.split('|', 4)
+                next unless details.size >= 3
+
+                pattern, replacement, line_offset_str, line_text = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  pattern: pattern,
+                  replacement: replacement,
+                  line_offset: line_offset_str.to_i,
+                  line_text: line_text || ''
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/informal_notation/result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InformalNotation
+          # Result wrapper for InformalNotation validator
+          # Formats parsed violations into offense objects
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'InformalNotation'
+
+            # Builds a human-readable message for the offense
+            # @param offense [Hash] offense details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/informal_notation/validator.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module InformalNotation
+          # Validates that documentation uses proper YARD tags instead of
+          # informal notation patterns like "Note:", "TODO:", etc.
+          class Validator < Base
+            # Enable in-process execution with public visibility
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Checks for informal notation patterns in docstrings.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              docstring_text = object.docstring.to_s
+              return if docstring_text.empty?
+
+              patterns = config_patterns
+              case_sensitive = config_case_sensitive
+              require_start = config_require_start_of_line
+
+              found_patterns = find_informal_patterns(
+                docstring_text,
+                patterns,
+                case_sensitive,
+                require_start
+              )
+
+              return if found_patterns.empty?
+
+              # Output format: two lines per violation
+              # Line 1: file:line: object_title
+              # Line 2: pattern|replacement|line_offset|line_text (pipe-separated)
+              found_patterns.each do |match|
+                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                collector.puts "#{match[:pattern]}|#{match[:replacement]}|" \
+                               "#{match[:line_offset]}|#{match[:line_text]}"
+              end
+            end
+
+            private
+
+            # Find informal patterns in docstring text, skipping code blocks
+            # @param docstring_text [String] the docstring text to scan
+            # @param patterns [Hash] pattern => replacement mapping
+            # @param case_sensitive [Boolean] whether to match case-sensitively
+            # @param require_start [Boolean] whether pattern must be at start of line
+            # @return [Array<Hash>] array of matches with pattern, replacement, line_offset, line_text
+            def find_informal_patterns(docstring_text, patterns, case_sensitive, require_start)
+              found_patterns = []
+              matched_lines = Set.new
+              in_code_block = false
+
+              docstring_text.lines.each_with_index do |line, line_offset|
+                # Track fenced code blocks (``` markers)
+                if line.strip.start_with?('```')
+                  in_code_block = !in_code_block
+                  next
+                end
+
+                # Skip lines inside code blocks
+                next if in_code_block
+
+                # Skip lines already matched (avoids duplicate reports for similar patterns)
+                next if matched_lines.include?(line_offset)
+
+                patterns.each do |pattern, replacement|
+                  next if replacement.nil? || replacement.empty?
+                  next unless matches_pattern?(line, pattern, case_sensitive, require_start)
+
+                  found_patterns << {
+                    pattern: pattern,
+                    replacement: replacement,
+                    line_offset: line_offset,
+                    line_text: line.strip
+                  }
+                  matched_lines.add(line_offset)
+                  break
+                end
+              end
+
+              found_patterns
+            end
+
+            # Check if a line matches the informal pattern
+            # @param line [String] the line to check
+            # @param pattern [String] the pattern to match (without colon)
+            # @param case_sensitive [Boolean] whether to match case-sensitively
+            # @param require_start [Boolean] whether pattern must be at start of line
+            # @return [Boolean] true if the line matches
+            def matches_pattern?(line, pattern, case_sensitive, require_start)
+              # Build regex for pattern followed by colon
+              escaped_pattern = Regexp.escape(pattern)
+
+              regex_str = if require_start
+                            # Match at start of line after optional whitespace
+                            "^\\s*#{escaped_pattern}:"
+                          else
+                            # Match anywhere in line (after start or whitespace)
+                            "(?:^|\\s)#{escaped_pattern}:"
+                          end
+
+              flags = case_sensitive ? nil : Regexp::IGNORECASE
+              regex = Regexp.new(regex_str, flags)
+
+              line.match?(regex)
+            end
+
+            # @return [Hash] configured patterns mapping informal -> YARD tag
+            def config_patterns
+              config_or_default('Patterns')
+            end
+
+            # @return [Boolean] whether matching should be case-sensitive
+            def config_case_sensitive
+              config_or_default('CaseSensitive')
+            end
+
+            # @return [Boolean] whether patterns must appear at start of line
+            def config_require_start_of_line
+              config_or_default('RequireStartOfLine')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/informal_notation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # InformalNotation validator
+        #
+        # Detects informal notation patterns in YARD documentation comments
+        # and suggests proper YARD tags. For example, "Note:" should use @note,
+        # "TODO:" should use @todo, etc.
+        #
+        # ## Configuration
+        #
+        # To customize which patterns are detected:
+        #
+        # ```yaml
+        # Tags/InformalNotation:
+        #   Enabled: true
+        #   CaseSensitive: false
+        #   RequireStartOfLine: true
+        #   Patterns:
+        #     Note: '@note'
+        #     TODO: '@todo'
+        # ```
+        #
+        # @example Good - Using proper YARD tags
+        #   # Calculate the sum of values
+        #   # @note This method is slow for large arrays
+        #   # @todo Optimize for performance
+        #   def sum(values)
+        #   end
+        #
+        # @example Bad - Using informal notation
+        #   # Calculate the sum of values
+        #   # Note: This method is slow for large arrays
+        #   # TODO: Optimize for performance
+        #   def sum(values)
+        #   end
+        module InformalNotation
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/invalid_types/validator.rb

@@ -9,94 +9,81 @@ module Yard
           # By invalid we mean, that they are not classes nor any of the allowed defaults or
           # exclusions.
           class Validator < Base
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
+
             # All non-class yard types that are considered valid
             ALLOWED_DEFAULTS = %w[
               false
               true
               nil
               self
-              vold
+              void
             ].freeze
 
             private_constant :ALLOWED_DEFAULTS
 
-            private
+            # Execute query for a single object during in-process execution.
+            # Checks for invalid type definitions in tags.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              checked_tags = config_or_default('ValidatedTags')
+              extra_types = config_or_default('ExtraTypes')
+              allowed_types = ALLOWED_DEFAULTS + extra_types
 
-            # Runs yard list query with proper settings on a given dir and files
-            # @param dir [String] dir where the yard db is (or where it should be generated)
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, file_list_path)
-              # Write query to a temporary file to avoid shell escaping issues
-              squery = Shellwords.escape(query)
-              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{squery} "
+              # Sanitize type string (remove type syntax characters)
+              sanitize = ->(type) { type.tr('=><>,{} ', '') }
 
-              Tempfile.create(['yard_query', '.sh']) do |f|
-                f.write("#!/bin/bash\n")
-                f.write(cmd)
-                f.write("--private --protected -b #{Shellwords.escape(dir)}\n")
-                f.flush
-                f.chmod(0o755)
+              # Check for invalid types
+              invalid_types = object.docstring.tags
+                                    .select { |tag| checked_tags.include?(tag.tag_name) }
+                                    .flat_map(&:types)
+                                    .compact
+                                    .uniq
+                                    .map(&sanitize)
+                                    .reject { |type| allowed_types.include?(type) }
+                                    .reject { |type| type_defined?(type) }
+                                    .reject { |type| type.include?('#') }
 
-                shell("bash #{Shellwords.escape(f.path)}")
-              end
-            end
-
-            # @return [String] multiline yard query that we use to find methods with
-            #   tags with invalid types definitions
-            def query
-              <<-QUERY
-                '
-                  sanitize = ->(type) do
-                    type
-                      .tr('=>', '')
-                      .tr('<', '')
-                      .tr('>', '')
-                      .tr(' ', '')
-                      .tr(',', '')
-                      .tr('{', '')
-                      .tr('}', '')
-                  end
+              return if invalid_types.empty?
 
-                  docstring
-                    .tags
-                    .select { |tag| #{checked_tags_names}.include?(tag.tag_name) }
-                    .map(&:types)
-                    .flatten
-                    .uniq
-                    .compact
-                    .map(&sanitize)
-                    .reject { |type| #{allowed_types_code}.include?(type) }
-                    .reject { |type| !(Kernel.const_defined?(type) rescue nil).nil? }
-                    .reject { |type| type.include?('#') }
-                    .then { |types| !types.empty? }
-                '
-              QUERY
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
             end
 
-            # @return [String] tags names for which we want to check the invalid tags
-            #   types definitions
-            def checked_tags_names
-              validated_tags = config_or_default('ValidatedTags')
-              query_array(validated_tags)
-            end
+            private
 
-            # @return [String] extra names that we allow for types definitions in a yard
-            #   query acceptable form
-            def allowed_types_code
-              extra_types = config_or_default('ExtraTypes')
-              query_array(ALLOWED_DEFAULTS + extra_types)
-            end
+            # Check if a type is defined in Ruby runtime or YARD registry
+            # In in-process mode, parsed classes are in YARD registry but not loaded into Ruby
+            # @param type [String] type name to check
+            # @return [Boolean] true if type is defined (or at least recognized as a valid type)
+            def type_defined?(type)
+              # Symbol types like :foo are valid YARD documentation notations
+              # They document that a method accepts specific symbol values
+              return true if type.start_with?(':')
 
-            # @param elements [Array<String>] array of elements that we want to convert into
-            #   a string ruby yard query array form
-            # @return [String] array of elements for yard query converted into a string
-            def query_array(elements)
-              "
-                [
-                    #{elements.map { |type| "'#{type}'" }.join(',')}
-                ]
-              "
+              # Check Ruby runtime first
+              # The shell query uses: !(Kernel.const_defined?(type) rescue nil).nil?
+              # This means: if const_defined? returns ANY value (true or false, not nil),
+              # the type is considered "recognized" and should not be flagged as invalid.
+              # This allows common types like "Boolean" which aren't actual Ruby classes
+              # but are still recognized by Ruby as valid constant names to check.
+              begin
+                const_result = Kernel.const_defined?(type)
+              rescue NameError
+                # Invalid constant name syntax (e.g., "foo<bar>" or names with special chars)
+                # These aren't valid Ruby constants, so we can't check them this way
+                const_result = nil
+              end
+              return true unless const_result.nil?
+
+              # Check YARD registry (for classes defined in parsed files)
+              # This may fail for malformed type strings or registry issues
+              !YARD::Registry.resolve(nil, type).nil?
+            rescue NameError
+              # Type couldn't be resolved - it's not defined
+              false
             end
           end
         end

data/lib/yard/lint/validators/tags/invalid_types.rb

@@ -28,7 +28,6 @@ module Yard
         #
         #     Tags/InvalidTypes:
         #       Enabled: false
-        #
         module InvalidTypes
         end
       end