Fix bracket/brace map corruption from Ruby 3.0+ pattern matching deconstruction (#1671)

# Description

In Ruby 3.0+ pattern matching, bracket-based and braced patterns fire
scanner events for their delimiters but do not fire the same parser
events as ordinary array indexing or hash literals. YARD had no handlers
for these pattern-match parser events, so entries were pushed to the
bracket/brace maps but never consumed. Since those maps are read
FIFO/LIFO by later expressions, the stale entries produced garbled
source ranges on the next array indexing or hash literal after a pattern
match.

Three event handlers are added:

- **`on_aryptn`**: Array patterns (`Bar['key', v]`, `Bar[a, b]`, bare
`[a, b]`) fire `on_aryptn` instead of `on_aref`. The handler pops from
`@map[:lbracket]` and shifts from `@map[:aref]`, mirroring what
`on_aref` would have done.
- **`on_fndptn`**: Find patterns (`Bar[*, v, *]`) fire `on_fndptn`
instead of `on_aref`. Same bracket map cleanup.
- **`on_hshptn`**: Braced hash patterns (`{ key: val }`) fire
`on_hshptn` instead of `on_hash`, leaving a stale entry in
`@map[:lbrace]`. To distinguish braced patterns from bare hash patterns
(`key: val`, which fire no brace scanner events), `on_rbrace` is
overridden to track closing brace positions in `@map[:rbrace]`.
`on_hshptn` cleans up both maps only when `@map[:rbrace]` confirms a
closing brace was scanned, using `||=` guards on both map accesses for
consistency with the rest of the map handling code. `visit_event` is
updated to drain `@map[:rbrace]` when consuming a `@map[:lbrace]` entry,
keeping the maps in sync for normal hash literals and brace blocks
(including the case where a braced pattern appears inside a brace
block).

Fixes #1547

# Completed Tasks

- [x] I have read the [Contributing Guide][contrib].
- [x] The pull request is complete (implemented / written).
- [x] Git commits have been cleaned up (squash WIP / revert commits).
- [x] I wrote tests and ran `bundle exec rake` locally (if code is
attached to PR).

[contrib]: https://github.com/lsegal/yard/blob/main/CONTRIBUTING.md

-----------------

# Description

Describe your pull request and problem statement here.

# Completed Tasks

- [ ] I have read the [Contributing Guide][contrib].
- [ ] The pull request is complete (implemented / written).
- [ ] Git commits have been cleaned up (squash WIP / revert commits).
- [ ] I wrote tests and ran `bundle exec rake` locally (if code is
attached to PR).

[contrib]: https://github.com/lsegal/yard/blob/main/CONTRIBUTING.md

Author: lsegal

lib/yard/parser/ruby/ruby_parser.rb

@@ -244,6 +244,7 @@ def visit_event(node)
             sstart = child_node.source_range.first
           else
             lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
+            (@map[:rbrace] ||= []).shift if map && MAPPINGS[node.type] == :lbrace
           end
 
           raise "Cannot determine start of node #{node} around #{file}:#{lineno}" if lstart.nil? || sstart.nil?
@@ -336,6 +337,7 @@ def add_token(token, data)
         undef on_aref_field
         undef on_lbracket
         undef on_rbracket
+        undef on_rbrace
         undef on_string_literal
         undef on_lambda
         undef on_unary
@@ -371,6 +373,20 @@ def on_hash(*args)
           visit_event AstNode.new(:hash, args.first || [])
         end
 
+        # Ruby 3.0+ pattern matching: braced hash patterns ({key: val} syntax) fire
+        # on_lbrace and on_rbrace scanner events. The corresponding parser event is
+        # on_hshptn (not on_hash), so we must clean up the brace maps to prevent stale
+        # entries from corrupting source ranges of later hash literals and brace blocks.
+        # Bare hash patterns (key: val without braces) fire no brace scanner events, so
+        # we only clean up when @map[:rbrace] confirms a closing brace was scanned.
+        def on_hshptn(*args)
+          if (@map[:rbrace] ||= []).any?
+            (@map[:lbrace] ||= []).pop
+            @map[:rbrace].shift
+          end
+          AstNode.new(:hshptn, args)
+        end
+
         def on_bare_assoc_hash(*args)
           AstNode.new(:list, args.first)
         end
@@ -422,6 +438,27 @@ def on_array(other)
           node
         end
 
+        # Ruby 3.0+ pattern matching: array patterns (SomeClass[a, b]) and find patterns
+        # (SomeClass[*pre, val, *post]) use [...] brackets, which fire on_lbracket and
+        # on_rbracket scanner events. The corresponding parser events are on_aryptn/on_fndptn
+        # (not on_aref), so we must clean up the bracket maps to prevent stale entries from
+        # corrupting source ranges of later array indexing expressions.
+        def on_aryptn(*args)
+          (@map[:lbracket] ||= []).pop
+          (@map[:aref] ||= []).shift
+          # Source range is intentionally not set; no handler is registered for
+          # pattern-match nodes, so they produce no documentation output.
+          AstNode.new(:aryptn, args)
+        end
+
+        def on_fndptn(*args)
+          (@map[:lbracket] ||= []).pop
+          (@map[:aref] ||= []).shift
+          # Source range is intentionally not set; no handler is registered for
+          # pattern-match nodes, so they produce no documentation output.
+          AstNode.new(:fndptn, args)
+        end
+
         def on_lbracket(tok)
           (@map[:lbracket] ||= []) << [lineno, charno]
           visit_ns_token(:lbracket, tok, false)
@@ -432,6 +469,13 @@ def on_rbracket(tok)
           visit_ns_token(:rbracket, tok, false)
         end
 
+        # Maintained explicitly (unlike on_lbracket/on_rbracket) so on_hshptn can
+        # distinguish braced from bare hash patterns in Ruby 3.0+ pattern matching.
+        def on_rbrace(tok)
+          (@map[:rbrace] ||= []) << [lineno, charno]
+          visit_ns_token(:rbrace, tok, false)
+        end
+
         def on_dyna_symbol(sym)
           rng = if sym.source_range.to_a.size == 0 # rubocop:disable Style/ZeroLengthPredicate
                   (sym.source_range.begin - 3)...sym.source_range.end

spec/parser/ruby/ruby_parser_spec.rb

@@ -679,6 +679,161 @@ def add(x) = x + 1
       end
     end if RUBY_VERSION >= '3.'
 
+    it "provides correct source range for aref after array pattern deconstruction" do
+      code = <<-RUBY
+class Foo
+  def check(obj)
+    case obj
+    in Bar["key", v]
+      v
+    end
+  end
+
+  def fetch(h)
+    h["result"]
+  end
+end
+      RUBY
+
+      parser = YARD::Parser::Ruby::RubyParser.new(code, nil)
+      ast = parser.parse.root
+
+      aref_node = nil
+      ast.traverse do |node|
+        if node.type == :aref
+          aref_node = node
+          break
+        end
+      end
+
+      expect(aref_node).not_to be_nil
+      expect(code[aref_node.source_range]).to eq('h["result"]')
+    end if RUBY_VERSION >= '3.'
+
+    it "provides correct source range for aref after find pattern deconstruction" do
+      code = <<-RUBY
+class Foo
+  def check(obj)
+    case obj
+    in Bar[*, v, *]
+      v
+    end
+  end
+
+  def fetch(h)
+    h["result"]
+  end
+end
+      RUBY
+
+      parser = YARD::Parser::Ruby::RubyParser.new(code, nil)
+      ast = parser.parse.root
+
+      aref_node = nil
+      ast.traverse do |node|
+        if node.type == :aref
+          aref_node = node
+          break
+        end
+      end
+
+      expect(aref_node).not_to be_nil
+      expect(code[aref_node.source_range]).to eq('h["result"]')
+    end if RUBY_VERSION >= '3.'
+
+    it "provides correct source range for hash literal after braced hash pattern deconstruction" do
+      code = <<-RUBY
+class Foo
+  def check(obj)
+    case obj
+    in { name: String }
+      "matched"
+    end
+  end
+
+  def build
+    { name: "Alice" }
+  end
+end
+      RUBY
+
+      parser = YARD::Parser::Ruby::RubyParser.new(code, nil)
+      ast = parser.parse.root
+
+      hash_node = nil
+      ast.traverse do |node|
+        if node.type == :hash
+          hash_node = node
+          break
+        end
+      end
+
+      expect(hash_node).not_to be_nil
+      expect(code[hash_node.source_range]).to eq('{ name: "Alice" }')
+    end if RUBY_VERSION >= '3.'
+
+    it "provides correct source range for aref after bare array pattern deconstruction" do
+      code = <<-RUBY
+class Foo
+  def check(obj)
+    case obj
+    in [a, b]
+      a
+    end
+  end
+
+  def fetch(h)
+    h["result"]
+  end
+end
+      RUBY
+
+      parser = YARD::Parser::Ruby::RubyParser.new(code, nil)
+      ast = parser.parse.root
+
+      aref_node = nil
+      ast.traverse do |node|
+        if node.type == :aref
+          aref_node = node
+          break
+        end
+      end
+
+      expect(aref_node).not_to be_nil
+      expect(code[aref_node.source_range]).to eq('h["result"]')
+    end if RUBY_VERSION >= '3.'
+
+    it "provides correct source range for hash literal after bare hash pattern deconstruction" do
+      code = <<-RUBY
+class Foo
+  def check(obj)
+    case obj
+    in name: String
+      "matched"
+    end
+  end
+
+  def build
+    { name: "Alice" }
+  end
+end
+      RUBY
+
+      parser = YARD::Parser::Ruby::RubyParser.new(code, nil)
+      ast = parser.parse.root
+
+      hash_node = nil
+      ast.traverse do |node|
+        if node.type == :hash
+          hash_node = node
+          break
+        end
+      end
+
+      expect(hash_node).not_to be_nil
+      expect(code[hash_node.source_range]).to eq('{ name: "Alice" }')
+    end if RUBY_VERSION >= '3.'
+
     it "provides correct range for `next` statement following `def` _symbol_" do
       code = <<-RUBY
 foo do