Fix aref_field bracket consumption causing invalid source_range (#1642)

# Description

Fixes #1420

I caused the above regression four years ago and am proposing a fix
here. This PR was heavily AI-assisted.

The issue occurred when parsing code with an `aref` assignment (`a[:b] =
1`) followed by a constant assignment using `aref` (`X = a[:b]`). The
parser would create an invalid `source_range` for the constant's `aref`
node, where the ending position was less than the beginning position.

Root Cause:
-----------
When Ripper encounters an aref on the left-hand side of an assignment
(e.g., `a[:b] = 1`), it calls `on_aref_field` instead of `on_aref`. The
`on_aref_field` method was not consuming the closing bracket position
from `@map[:aref]`, which tracks bracket positions. This left the
bracket position from the assignment in the map.

When the next aref expression (`X = a[:b]`) was parsed, `on_aref` would
shift the old bracket position from `@map[:aref]`, causing it to use the
wrong ending position and create an invalid `source_range` where `end` <
`begin`.

The Fix:
--------
Updated on_aref_field to match the behavior of `on_aref`:
- Consume the closing bracket position from `@map[:aref]` using shift
- Use the bracket position to correctly calculate the `source_range`
- Set both `source_range` and `line_range` based on the actual bracket
position

This ensures that when `on_aref_field` processes `a[:b] = 1`, it
consumes the bracket, so when `on_aref` processes `X = a[:b]`, it gets
the correct bracket position and creates a valid source_range.

Changes:
--------
- Modified `on_aref_field` in `lib/yard/parser/ruby/ruby_parser.rb` to
consume bracket positions from `@map[:aref]` and calculate source_range
correctly
- Added spec to verify constant assignments with `aref` after `aref`
assignments parse correctly with valid `source_range`

The fix ensures both `on_aref` and `on_aref_field` handle bracket
consumption consistently, preventing the parser from getting confused by
previous `aref` assignments.

# 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

Author: lsegal

lib/yard/parser/ruby/ruby_parser.rb

@@ -398,8 +398,10 @@ def on_aref(*args)
 
         def on_aref_field(*args)
           @map[:lbracket].pop
-          AstNode.new(:aref_field, args,
-                      :listline => lineno..lineno, :listchar => charno...charno)
+          ll, lc = *@map[:aref].shift
+          sr = args.first.source_range.begin..lc
+          lr = args.first.line_range.begin..ll
+          AstNode.new(:aref_field, args, :char => sr, :line => lr)
         end
 
         def on_array(other)

spec/parser/ruby/ruby_parser_spec.rb

@@ -702,5 +702,55 @@ def add(x) = x + 1
       expect(next_node.line_range).to eq(3..3)
       expect(code[next_node.source_range]).to eq('next')
     end
+
+    # @bug gh-1420
+    it "parses constant assignment with aref after aref assignment correctly" do
+      code = <<-RUBY
+module Foo
+  a = {}
+
+  # Earlier assignment
+  a[:b] = 1
+
+  # This constant fails to parse correctly
+  X = a[:b]
+end
+      RUBY
+
+      parser = YARD::Parser::Ruby::RubyParser.new(code, nil)
+      ast = parser.parse.root
+
+      # Find the constant assignment node (X = a[:b])
+      assign_node = nil
+      ast.traverse do |node|
+        if node.type == :assign
+          # Check if it's a constant assignment (X = a[:b])
+          # Structure: assign[0] = var_field containing const "X"
+          #           assign[1] = aref node (a[:b])
+          lhs = node[0]
+          rhs = node[1]
+          if lhs && lhs.type == :var_field && lhs[0] && lhs[0].type == :const &&
+             (lhs[0][0] == "X" || lhs[0][0] == :X) && rhs && rhs.type == :aref
+            assign_node = node
+            break
+          end
+        end
+      end
+
+      expect(assign_node).not_to be_nil, "Should find constant assignment X = a[:b]"
+
+      # Check that the aref node (a[:b]) has a valid source_range
+      # The bug causes the ending position to be less than the beginning position
+      aref_node = assign_node[1]
+      expect(aref_node.type).to eq :aref
+      expect(aref_node.source_range).not_to be_nil
+      expect(aref_node.source_range.end).to be >= aref_node.source_range.begin,
+        "aref node source_range should be valid (ending >= beginning), got #{aref_node.source_range.inspect}. " \
+        "This indicates the parser got confused by the previous aref assignment."
+
+      # Verify the source can be extracted correctly
+      extracted_source = code[aref_node.source_range]
+      expect(extracted_source).to eq "a[:b]"
+    end
   end
 end if HAVE_RIPPER