yard-lint 1.6.1 → 1.7.0

data/lib/yard/lint/validators/documentation/orphaned_doc_comment/validator.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'ripper'
+require 'set'
+
 module Yard
   module Lint
     module Validators
@@ -31,6 +34,8 @@ module Yard
               (def |class |module |attr_reader|attr_writer|attr_accessor|attr_internal|attr\b|alias_method\b|alias\b|define_method\b)
               |
               \A\s*[A-Z][A-Za-z0-9_:]*\s*=
+              |
+              \A\s*\w+\s+def\b
             /x.freeze
 
             # Matches a DSL-style method call whose first argument is a symbol or string literal
@@ -38,7 +43,13 @@ module Yard
             # YARD's DSL handler turns such a call into a documentable method object when the
             # preceding comment carries an implicit-docstring tag, so a doc comment in front of
             # one of these is NOT orphaned.
-            DSL_CALL_PATTERN = /\A\s*(?<method>[a-z_]\w*[!?]?)(?:\s+|\s*\(\s*)(?::\w|:["']|["'])/.freeze
+            DSL_CALL_PATTERN = %r{\A\s*(?:[A-Za-z_][\w:]*\.)?(?<method>[a-z_]\w*[!?]?)(?:\s+|\s*\(\s*)(?::\w|:["']|["'])}.freeze
+            # Matches a plain method call (optionally with a receiver), used when
+            # the comment carries a @method/@attribute tag that names the object
+            # YARD creates - then the call's argument shape does not matter.
+            METHOD_CALL_PATTERN = /\A\s*(?:[A-Za-z_][\w:]*\.)?[a-z_]\w*[!?]?(?:[\s(]|\z)/.freeze
+            # Matches a @method/@attribute tag that names a created object.
+            NAMED_OBJECT_TAG_PATTERN = /\A\s*#\s*@(?:method|attribute)\s+\S/.freeze
             # Mirror of YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS - calls to these
             # are skipped by YARD's DSL handler, so a preceding doc comment really is dropped.
             # (The `attr*`/`alias*` entries are already covered by DEFINITION_PATTERN.)
@@ -74,19 +85,26 @@ module Yard
             # @param collector [Executor::ResultCollector] collector for output lines
             # @return [void]
             def scan_file(file, collector)
-              lines = File.readlines(file, chomp: true)
+              source = File.read(file)
+              lines = source.lines.map(&:chomp)
+              # Line indices (0-based) that hold a real, full-line Ruby comment.
+              # Derived from the lexer so that '#'-leading lines inside heredocs
+              # and string literals are not mistaken for documentation comments.
+              comment_lines = full_line_comment_indices(source, lines)
               i = 0
 
               while i < lines.length
-                if comment_line?(lines[i])
+                if comment_line?(lines[i], i, comment_lines)
                   block_start = i
                   tags = []
 
                   has_directive = false
                   has_implicit_tag = false
-                  while i < lines.length && comment_line?(lines[i])
+                  has_named_object_tag = false
+                  while i < lines.length && comment_line?(lines[i], i, comment_lines)
                     has_directive = true if directive_line?(lines[i])
                     has_implicit_tag = true if implicit_docstring_tag?(lines[i])
+                    has_named_object_tag = true if lines[i].match?(NAMED_OBJECT_TAG_PATTERN)
                     tag = extract_yard_tag(lines[i])
                     tags << tag if tag
                     i += 1
@@ -99,7 +117,7 @@ module Yard
                   # Skip trailing blank lines after the comment block
                   i += 1 while i < lines.length && lines[i].strip.empty?
 
-                  unless documentable?(lines[i], has_implicit_tag)
+                  unless documentable?(lines[i], has_implicit_tag, has_named_object_tag)
                     collector.puts "#{file}:#{block_start + 1}: #{tags.uniq.join(',')}"
                   end
                 else
@@ -108,17 +126,60 @@ module Yard
               end
             end
 
+            # Lex the source and collect the 0-based indices of lines whose first
+            # non-whitespace content is a Ruby comment. Heredoc bodies and string
+            # literals lex as content tokens (not `:on_comment`), so their
+            # `#`-leading lines are excluded - fixing the false positives where
+            # tag-looking text inside a heredoc was treated as a doc comment.
+            # @param source [String] the full file source
+            # @param lines [Array<String>] the source split into chomped lines
+            # @return [Set<Integer>] 0-based indices of full-line comments
+            def full_line_comment_indices(source, lines)
+              indices = Set.new
+              ::Ripper.lex(source).each do |(position, type, _token, _state)|
+                next unless type == :on_comment
+
+                line_no, column = position
+                index = line_no - 1
+                current = lines[index]
+                next unless current
+
+                # Only a full-line comment (nothing but whitespace before the '#').
+                indices << index if current[0...column].to_s.strip.empty?
+              end
+              indices
+            rescue StandardError
+              # If the source cannot be lexed, fall back to the previous regex
+              # behaviour so a single unparseable file does not lose detection.
+              fallback = Set.new
+              lines.each_with_index do |line, index|
+                fallback << index if line.strip.start_with?('#')
+              end
+              fallback
+            end
+
             # @param line [String] a raw source line
+            # @param index [Integer] 0-based line index
+            # @param comment_lines [Set<Integer>] indices of real full-line comments
             # @return [Boolean] true if the line is a Ruby comment (excluding magic comments)
-            def comment_line?(line)
-              stripped = line.strip
-              stripped.start_with?('#') && !magic_comment?(stripped)
+            def comment_line?(line, index, comment_lines)
+              return false unless comment_lines.include?(index)
+
+              !magic_comment?(line.strip)
             end
 
             # @param stripped_line [String] a comment line with leading/trailing whitespace removed
             # @return [Boolean] true if the line is a Ruby magic comment (frozen_string_literal, encoding, etc.)
             def magic_comment?(stripped_line)
-              stripped_line.match?(/\A#\s*(frozen[_-]string[_-]literal|encoding|warn[_-]indent|shareable[_-]constant[_-]value)\s*:/i)
+              # A real magic comment has a single-token value (e.g. `true`,
+              # `utf-8`), optionally followed by `;` (combined directives) or an
+              # emacs `-*-` wrapper. Requiring that avoids treating prose that
+              # merely starts with a magic-comment word - like
+              # `# encoding: UTF-8 is assumed for all inputs` - as a magic
+              # comment, which would split a documentation block.
+              stripped_line.match?(
+                /\A#\s*(?:-\*-\s*)?(frozen[_-]string[_-]literal|encoding|warn[_-]indent|shareable[_-]constant[_-]value)\s*:\s*\S+\s*(?:;|-\*-|\z)/i
+              )
             end
 
             # @param line [String] a raw source line
@@ -137,11 +198,18 @@ module Yard
             # @param line [String, nil] the source line following the comment block, or nil at EOF
             # @param has_implicit_tag [Boolean] whether the comment block carries a tag that makes
             #   YARD's DSL handler emit a method object (see IMPLICIT_DOCSTRING_TAG_PATTERN)
+            # @param has_named_object_tag [Boolean] whether the comment block carries a
+            #   @method/@attribute tag naming the object YARD creates, so any following
+            #   method call attaches the docstring regardless of its arguments
             # @return [Boolean] true if YARD will attach the comment to a documentable construct
-            def documentable?(line, has_implicit_tag)
+            def documentable?(line, has_implicit_tag, has_named_object_tag = false)
               return false if line.nil?
 
-              definition_line?(line) || (has_implicit_tag && dsl_method_line?(line))
+              definition_line?(line) ||
+                (has_implicit_tag && dsl_method_line?(line)) ||
+                # A @method/@attribute tag names the object YARD creates, so any
+                # following method call (regardless of its arguments) attaches it.
+                (has_named_object_tag && line.match?(METHOD_CALL_PATTERN))
             end
 
             # @param line [String] a raw source line

data/lib/yard/lint/validators/documentation/orphaned_doc_comment.rb

@@ -15,10 +15,6 @@ module Yard
         # non-documentable statement (variable assignment, `require`, `include`, etc.)
         # or sits at the end of a file.
         #
-        # @note This validator is complementary to `Documentation/BlankLineBeforeDefinition`,
-        #   which catches doc blocks separated from a `def` by blank lines.
-        #   `OrphanedDocComment` catches doc blocks that lead to non-definition code entirely.
-        #
         # @example Bad - comment before variable assignment
         #   # @param name [String] the name
         #   # @return [void]
@@ -39,6 +35,10 @@ module Yard
         #   def process(name)
         #   end
         #
+        # @note This validator is complementary to `Documentation/BlankLineBeforeDefinition`,
+        #   which catches doc blocks separated from a `def` by blank lines.
+        #   `OrphanedDocComment` catches doc blocks that lead to non-definition code entirely.
+        #
         # ## Configuration
         #
         # To disable this validator:

data/lib/yard/lint/validators/documentation/text_substitution/validator.rb

@@ -16,6 +16,7 @@ module Yard
             def in_process_query(object, collector)
               docstring_text = object.docstring.to_s
               return if docstring_text.empty?
+              return if duplicate_docstring?(object)
 
               substitutions = config_or_default('Substitutions')
               return if substitutions.nil? || substitutions.empty?
@@ -24,7 +25,8 @@ module Yard
               return if violations.empty?
 
               violations.each do |violation|
-                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                line = docstring_line(object, violation[:line_offset])
+                collector.puts "#{object.file}:#{line}: #{object.title}"
                 collector.puts violation[:forbidden]
                 collector.puts violation[:replacement]
                 collector.puts "#{violation[:line_offset]}|#{violation[:line_text]}"
@@ -48,10 +50,16 @@ module Yard
                 end
                 next if in_code_block
 
+                # Match against the line with inline code spans (`...`) removed,
+                # so a forbidden string that only appears inside code is not
+                # flagged - it is literal code, not prose to be substituted. The
+                # reported line_text remains the original line.
+                scannable = line.gsub(/`[^`]*`/, '')
+
                 substitutions.each do |forbidden, replacement|
                   next if forbidden.nil? || forbidden.empty?
                   next if replacement.nil? || replacement.empty?
-                  next unless line.include?(forbidden)
+                  next unless scannable.include?(forbidden)
 
                   violations << {
                     forbidden: forbidden,

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/config.rb

@@ -12,7 +12,16 @@ module Yard
               'Enabled' => true,
               'Severity' => 'warning',
               'AllowedParentClasses' => [],
-              'AllowedMethods' => []
+              'AllowedMethods' => [],
+              # Match each parameter to a @param tag by name (default). Catches a
+              # misnamed @param (e.g. `@param wrong` for `def push(item)`) that a
+              # count-only check would accept. Set to false to fall back to the
+              # lenient count-only comparison.
+              'CheckParameterNames' => true,
+              # Opt-in: skip methods with no documentation at all and let
+              # Documentation/UndocumentedObjects report them, avoiding a second
+              # offense for the same fully-undocumented method. Off by default.
+              'SkipFullyUndocumented' => false
             }.freeze
           end
         end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/parser.rb

@@ -9,9 +9,13 @@ module Yard
           # @example Output format (skip-lint)
           #   /path/to/file.rb:10: Platform::Analysis::Authors#initialize
           class Parser < Parsers::Base
-            # Regex to extract file, line, and method name from yard list output
+            # Regex to extract file, line, and object title from yard list output
             # Format: /path/to/file.rb:10: ClassName#method_name
-            LOCATION_REGEX = /^(.+):(\d+):\s+(.+)[#.](.+)$/
+            LOCATION_REGEX = /^(.+):(\d+):\s+(.+)$/
+            # Splits an object title into namespace and method name on the last
+            # # or . separator. Top-level methods (#foo) have an empty namespace;
+            # titles without a separator (e.g. Foo::Bar, CONST) are kept whole.
+            TITLE_REGEX = /\A(.*)[#.]([^#.]+)\z/
 
             # @param yard_list [String] raw yard list results string
             # @return [Array<Hash>] Array with undocumented method arguments details
@@ -26,8 +30,7 @@ module Yard
                   # Extract: file path, line number, class name, method name
                   file_path = match_data[1]
                   line_number = match_data[2].to_i
-                  class_name = match_data[3]
-                  method_name = match_data[4]
+                  class_name, method_name = split_title(match_data[3])
 
                   {
                     location: file_path,
@@ -37,6 +40,17 @@ module Yard
                   }
                 end
             end
+
+            private
+
+            # Splits a YARD object title into namespace and method name parts
+            # @param title [String] object title (e.g. "Foo#bar", "#bar", "CONST")
+            # @return [Array(String, String)] namespace and method name; for titles
+            #   without a separator both parts are the full title
+            def split_title(title)
+              match = title.match(TITLE_REGEX)
+              match ? [match[1], match[2]] : [title, title]
+            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/undocumented_method_arguments/validator.rb

@@ -27,14 +27,48 @@ module Yard
               # doesn't need explicit @param documentation, matching attr_accessor behavior
               return if object.is_attribute?
 
-              # Check if parameters count exceeds @param tags count
-              param_count = object.parameters.size
-              param_tags_count = object.tags(:param).size
+              # Splat (*args, **opts) and block (&block) parameters are excluded -
+              # blocks are documented with @yield rather than @param, matching the
+              # arity convention used everywhere else in the gem (e.g. method_allowed?).
+              params = object.parameters.reject { |p| p[0].to_s.start_with?('*', '&') }
+              return if params.empty?
 
-              return unless param_count > param_tags_count
+              # Opt-in: defer fully-undocumented methods to
+              # Documentation/UndocumentedObjects instead of reporting them here too.
+              return if config_or_default('SkipFullyUndocumented') && object.docstring.blank?
+
+              return unless arguments_missing_docs?(object, params)
 
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
             end
+
+            private
+
+            # Decide whether a method's parameters are under-documented.
+            # @param object [YARD::CodeObjects::MethodObject] the method to check
+            # @param params [Array<Array>] non-splat/block parameters
+            # @return [Boolean] true if documentation is missing
+            def arguments_missing_docs?(object, params)
+              # Tags nested inside @overload blocks live on the overload's own
+              # docstring, so all_typed_tags collects those @param tags too.
+              param_tags = all_typed_tags(object.docstring, %w[param])
+
+              if config_or_default('CheckParameterNames')
+                documented = param_tags.map { |tag| normalize_param_name(tag.name) }
+                params.any? { |param| !documented.include?(normalize_param_name(param[0])) }
+              else
+                params.size > param_tags.size
+              end
+            end
+
+            # Normalize a parameter or @param name for comparison by stripping a
+            # trailing `:` - keyword parameters appear as `name:` in
+            # object.parameters but `name` in @param tag names.
+            # @param name [String, Symbol, nil] the raw name
+            # @return [String] the normalized name
+            def normalize_param_name(name)
+              name.to_s.sub(/:\z/, '')
+            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/undocumented_objects/parser.rb

@@ -62,6 +62,12 @@ module Yard
             # @param excluded_methods [Array<String>] list of exclusion patterns
             # @return [Boolean] true if method should be excluded
             def method_excluded?(element, arity, excluded_methods)
+              # ExcludedMethods only applies to methods. A class, module, or
+              # constant element has no #/. separator, so never derive a
+              # "method name" from it - otherwise a pattern like /cache/ would
+              # silently suppress the offense for a class such as Memcached.
+              return false unless element.match?(/[#.]/)
+
               # Extract method name from element (e.g., "Foo::Bar#baz" -> "baz")
               method_name = element.split(/[#.]/).last
               return false unless method_name

data/lib/yard/lint/validators/documentation/undocumented_options/validator.rb

@@ -32,6 +32,11 @@ module Yard
 
               return unless has_options_param
 
+              # A named (non-splat) parameter documented with a concrete
+              # non-Hash type (via its param tag) is not an options hash, so it
+              # does not need option tags.
+              return if options_param_documented_as_non_hash?(object)
+
               # Check if @option tags are missing
               option_tags = object.tags(:option)
               return unless option_tags.empty?
@@ -40,6 +45,31 @@ module Yard
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
               collector.puts params.map { |p| p.join(' ') }.join(', ')
             end
+
+            private
+
+            # Whether a named options-style parameter is documented with a
+            # concrete non-Hash @param type (e.g. `@param option [Symbol]`).
+            # Double-splat (`**opts`) collectors are always hashes and excluded.
+            # @param object [YARD::CodeObjects::MethodObject] the method
+            # @return [Boolean]
+            def options_param_documented_as_non_hash?(object)
+              param_tags = all_typed_tags(object.docstring, %w[param])
+
+              object.parameters.any? do |param|
+                name = param[0].to_s
+                next false if name.start_with?('**')
+
+                bare = name.gsub(/[*:]/, '')
+                next false unless bare.match?(/\A(options?|opts?|kwargs)\z/)
+
+                tag = param_tags.find { |t| t.name == bare }
+                types = tag&.types
+                next false if types.nil? || types.empty?
+
+                types.none? { |type| type.to_s.match?(/\AHash\b|\AHash[<{(]/) }
+              end
+            end
           end
         end
       end

data/lib/yard/lint/validators/semantic/abstract_methods/result.rb

@@ -28,6 +28,7 @@ module Yard
                   severity: configured_severity,
                   type: self.class.offense_type,
                   name: offense_data[:name] || self.class.offense_name,
+                  validator: validator_name,
                   message: build_message(offense_data),
                   location: offense_data[:location] || offense_data[:file],
                   location_line: offense_data[:line] || offense_data[:location_line] || 0

data/lib/yard/lint/validators/semantic/abstract_methods/validator.rb

@@ -32,11 +32,21 @@ module Yard
               # Skip def line and end
               body_lines = lines[1...-1] || []
 
+              # Merge statement continuations (a line ending in a comma or
+              # backslash continues on the next line) so a multi-line
+              # `raise NotImplementedError, "message"` is judged as one
+              # statement rather than leaving a dangling argument line that
+              # looks like a real implementation.
+              body_lines = merge_continuations(body_lines)
+
+              # A line is an allowed (non-)implementation if it is a comment,
+              # the closing `end`, or matches one of the configured
+              # AllowedImplementations patterns (e.g. raising NotImplementedError).
+              allowed = allowed_implementation_patterns
               has_real_implementation = body_lines.any? do |line|
-                !line.start_with?('#') &&
-                  !line.include?('NotImplementedError') &&
-                  !line.include?('raise') &&
-                  line != 'end'
+                next false if line.start_with?('#') || line == 'end'
+
+                allowed.none? { |pattern| line.match?(pattern) }
               end
 
               return unless has_real_implementation
@@ -44,6 +54,35 @@ module Yard
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
               collector.puts 'has_implementation'
             end
+
+            private
+
+            # The configured AllowedImplementations patterns compiled to
+            # regexps. A body line matching any of these does not count as a
+            # real implementation. Invalid patterns are ignored.
+            # @return [Array<Regexp>]
+            def allowed_implementation_patterns
+              Array(config_or_default('AllowedImplementations')).filter_map do |pattern|
+                Regexp.new(pattern.to_s)
+              rescue RegexpError
+                nil
+              end
+            end
+
+            # Joins lines that are continuations of the previous statement (the
+            # previous line ends with a comma or a backslash) into a single
+            # logical line.
+            # @param lines [Array<String>] stripped body lines
+            # @return [Array<String>] body lines with continuations merged
+            def merge_continuations(lines)
+              lines.each_with_object([]) do |line, merged|
+                if !merged.empty? && merged.last.match?(/[,\\]\z/)
+                  merged[-1] = "#{merged.last.chomp('\\').rstrip} #{line}"
+                else
+                  merged << line
+                end
+              end
+            end
           end
         end
       end

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

@@ -19,7 +19,12 @@ module Yard
               allowed_list = allowed_apis
 
               if object.has_tag?(:api)
-                api_value = object.tag(:api).text
+                # YARD tag text includes indented continuation/description lines
+                # (e.g. "private\nfor internal use only"). The @api value is a
+                # single token, so validate only the first word - otherwise a
+                # documented `@api private` is flagged as invalid, and the
+                # newline in the emitted value corrupts the parser's pairing.
+                api_value = object.tag(:api).text.to_s.split(/\s+/).first.to_s
                 unless allowed_list.include?(api_value)
                   collector.puts "#{object.file}:#{object.line}: #{object.title}"
                   collector.puts "invalid:#{api_value}"
@@ -37,6 +42,11 @@ module Yard
                 # hit the branch above and get their value validated. See issue #128.
                 return if object.type == :method && object.is_attribute?
 
+                # An api tag is expected on classes, modules, and methods (per
+                # this validator's documentation) - not on constants or other
+                # object types, which were being flagged as missing the tag.
+                return unless %i[class module method].include?(object.type)
+
                 # Only check public methods/classes if require_api_tags is enabled
                 visibility = object.visibility.to_s
                 if visibility == 'public' && !object.root?

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

@@ -54,13 +54,44 @@ module Yard
                   # (String, Integer) -> Array(String, Integer)
                   "Array#{type_string}"
                 else
-                  # Hash<K, V> -> Hash{K => V}
-                  type_string.gsub(/Hash<(.+?)>/) do
-                    types = ::Regexp.last_match(1)
-                    # Split on comma, handle nested types
-                    "Hash{#{types.sub(/,\s*/, ' => ')}}"
+                  # Hash<K, V> -> Hash{K => V}, handling nested generics with
+                  # balanced-bracket splitting so the suggestion stays valid.
+                  convert_hash_short_to_long(type_string)
+                end
+              end
+
+              # Converts Hash<K, V> to Hash{K => V}, recursing into the key and
+              # value and splitting on the top-level comma so nested types like
+              # Hash<Symbol, Hash<String, Integer>> are not mangled.
+              # @param type_string [String] the type string
+              # @return [String] the converted type string
+              def convert_hash_short_to_long(type_string)
+                match = type_string.match(/\AHash<(.+)>\z/m)
+                return type_string unless match
+
+                key, value = split_top_level(match[1])
+                return type_string unless value
+
+                "Hash{#{convert_hash_short_to_long(key.strip)} => " \
+                  "#{convert_hash_short_to_long(value.strip)}}"
+              end
+
+              # Splits a generic body on its first top-level comma, respecting
+              # nested <>, {}, and () so nested generics are kept intact.
+              # @param str [String] the inside of a generic (without the brackets)
+              # @return [Array] [key, value], or [str, nil] when there is no
+              #   top-level comma
+              def split_top_level(str)
+                depth = 0
+                str.each_char.with_index do |char, index|
+                  case char
+                  when '<', '{', '(' then depth += 1
+                  when '>', '}', ')' then depth -= 1
+                  when ','
+                    return [str[0...index], str[(index + 1)..]] if depth.zero?
                   end
                 end
+                [str, nil]
               end
 
               # Converts long syntax to short syntax

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

@@ -20,9 +20,10 @@ module Yard
               style = enforced_style
 
               all_typed_tags(object.docstring, validated_tags).each do |tag|
-                next unless tag.types
+                types = tag_data(tag).types
+                next unless types
 
-                tag.types.each do |type_str|
+                types.each do |type_str|
                   detected_style = detect_style(type_str)
 
                   # Report violations based on enforced style
@@ -41,22 +42,25 @@ module Yard
             # @param type_str [String] the type string to check
             # @return [String, nil] 'long' or 'short', or nil if not a collection type
             def detect_style(type_str)
+              # The Hash/Array prefixes are anchored with a negative lookbehind
+              # so only the built-in classes match - not custom classes whose
+              # names merely contain them (MyHash, ByteArray).
               # Hash types
               # Hash<...> is short style (should be Hash{K => V})
-              if type_str =~ /Hash<.*>/
+              if type_str =~ /(?<![A-Za-z0-9_])Hash<.*>/
                 'short'
               # Hash{...} is long style
-              elsif type_str =~ /Hash\{.*\}/
+              elsif type_str =~ /(?<![A-Za-z0-9_])Hash\{.*\}/
                 'long'
               # {...} without Hash prefix is short style
               elsif type_str =~ /^\{.*\}$/
                 'short'
               # Array types
               # Array<...> is long style
-              elsif type_str =~ /Array<.*>/
+              elsif type_str =~ /(?<![A-Za-z0-9_])Array<.*>/
                 'long'
               # Array(...) is long style
-              elsif type_str =~ /Array\(.*\)/
+              elsif type_str =~ /(?<![A-Za-z0-9_])Array\(.*\)/
                 'long'
               # <...> without Array prefix is short style
               elsif type_str =~ /^<.*>$/

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

@@ -28,7 +28,7 @@ module Yard
                 code = example.text
                 next if code.nil? || code.empty?
 
-                example_name = example.name || "Example #{index + 1}"
+                example_name = example.name.to_s.empty? ? "Example #{index + 1}" : example.name
 
                 # Run linter (pass file path for context/config discovery)
                 offenses = runner.run(code, example_name, file_path: object.file)

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

@@ -10,7 +10,12 @@ module Yard
             self.id = :example_syntax
             self.defaults = {
               'Enabled' => true,
-              'Severity' => 'warning'
+              'Severity' => 'warning',
+              # Opt-in: skip @example blocks that are interactive console
+              # transcripts (irb/pry sessions, their `=>` output, or shell `$`
+              # prompts) rather than runnable Ruby. Off by default so a real
+              # syntax error in a normal example is not accidentally hidden.
+              'SkipNonRuby' => false
             }.freeze
           end
         end