Fix broken legacy rdoc-ref labels and duplicate heading IDs

Decode legacy CGI-encoded labels (e.g., `What-27s+Here`) in rdoc-ref
links so they resolve to the correct GitHub-style anchors. Also
deduplicate heading IDs by appending -1, -2, etc. when multiple
headings produce the same anchor (e.g., "Method match" and
"Method match?" both becoming `method-match`).

Fixes #1590

Author: st0012

lib/rdoc/markup/to_html.rb

@@ -282,6 +282,7 @@ def start_accepting
     @res = []
     @in_list_entry = []
     @list = []
+    @heading_ids = {}
   end
 
   ##
@@ -412,8 +413,8 @@ def accept_blank_line(blank_line)
   def accept_heading(heading)
     level = [6, heading.level].min
 
-    label = heading.label @code_object
-    legacy_label = heading.legacy_label @code_object
+    label = deduplicate_heading_id(heading.label(@code_object))
+    legacy_label = deduplicate_heading_id(heading.legacy_label(@code_object))
 
     # Add legacy anchor before the heading for backward compatibility.
     # This allows old links with label- prefix to still work.
@@ -468,6 +469,20 @@ def accept_table(header, body, aligns)
 
   # :section: Utilities
 
+  ##
+  # Returns a unique heading ID, appending -1, -2, etc. for duplicates.
+  # Matches GitHub's behavior for duplicate heading anchors.
+
+  def deduplicate_heading_id(id)
+    if @heading_ids.key?(id)
+      @heading_ids[id] += 1
+      "#{id}-#{@heading_ids[id]}"
+    else
+      @heading_ids[id] = 0
+      id
+    end
+  end
+
   ##
   # CGI-escapes +text+
 

lib/rdoc/markup/to_html_crossref.rb

@@ -61,8 +61,11 @@ def cross_reference(name, text = nil, code = true, rdoc_ref: false)
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
 
-    if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
-      text ||= [CGI.unescape($'), (" at <code>#{$1}</code>" if $~.begin(1))].join("")
+    if !name.end_with?('+@', '-@') && match = name.match(/(.*[^#:])?@(.*)/)
+      context_name = match[1]
+      label = RDoc::Text.decode_legacy_label(match[2])
+      text ||= "#{label} at <code>#{context_name}</code>" if context_name
+      text ||= label
       code = false
     else
       text ||= name
@@ -168,9 +171,10 @@ def link(name, text, code = true, rdoc_ref: false)
       end
 
       if label
-        # Convert label to GitHub-style anchor format
-        # First convert + to space (URL encoding), then apply GitHub-style rules
-        formatted_label = RDoc::Text.to_anchor(label.tr('+', ' '))
+        # Decode legacy labels (e.g., "What-27s+Here" -> "What's Here")
+        # then convert to GitHub-style anchor format
+        decoded_label = RDoc::Text.decode_legacy_label(label)
+        formatted_label = RDoc::Text.to_anchor(decoded_label)
 
         # Case 1: Path already has an anchor (e.g., method link)
         #   Input:  C1#method@label -> path="C1.html#method-i-m"
@@ -181,7 +185,7 @@ def link(name, text, code = true, rdoc_ref: false)
         # Case 2: Label matches a section title
         #   Input:  C1@Section -> path="C1.html", section "Section" exists
         #   Output: C1.html#section (uses section.aref for GitHub-style)
-        elsif (section = ref&.sections&.find { |s| label.tr('+', ' ') == s.title })
+        elsif (section = ref&.sections&.find { |s| decoded_label == s.title })
           path << "##{section.aref}"
 
         # Case 3: Ref has an aref (class/module context)

lib/rdoc/text.rb

@@ -335,4 +335,27 @@ def wrap(txt, line_len = 76)
     text.downcase.gsub(/[^a-z0-9 \-]/, '').gsub(' ', '-')
   end
 
+  ##
+  # Decodes a label that may be in legacy RDoc format where CGI.escape was
+  # applied and then '%' was replaced with '-'. Converts '+' to space,
+  # then reverses -XX hex encoding for non-alphanumeric characters.
+  #
+  # Labels in new format pass through unchanged because -XX patterns that
+  # decode to alphanumeric characters are left as-is (CGI.escape never
+  # encodes alphanumerics).
+  #
+  # Examples:
+  #   "What-27s+Here"  -> "What's Here"  (legacy: -27 is apostrophe)
+  #   "Foo-3A-3ABar"   -> "Foo::Bar"     (legacy: -3A is colon)
+  #   "Whats-Here"     -> "Whats-Here"   (new format, unchanged)
+
+  module_function def decode_legacy_label(label)
+    label = label.tr('+', ' ')
+    label.gsub!(/-([0-7][0-9A-F])/) do
+      char = [$1.hex].pack('C')
+      char.match?(/[a-zA-Z0-9]/) ? $& : char
+    end
+    label
+  end
+
 end

test/rdoc/markup/to_html_crossref_test.rb

@@ -111,6 +111,23 @@ def test_convert_CROSSREF_section_with_spaces
     assert_equal para("<a href=\"C1.html#public-methods\">Public Methods at <code>C1</code></a>"), result
   end
 
+  def test_convert_CROSSREF_legacy_label
+    result = @to.convert 'C1@What-27s+Here'
+    assert_equal para("<a href=\"C1.html#class-c1-whats-here\">What\u2019s Here at <code>C1</code></a>"), result
+  end
+
+  def test_convert_CROSSREF_legacy_label_colon
+    result = @to.convert 'C1@Foo-3A-3ABar'
+    assert_equal para("<a href=\"C1.html#class-c1-foobar\">Foo::Bar at <code>C1</code></a>"), result
+  end
+
+  def test_convert_CROSSREF_legacy_section
+    @c1.add_section "What's Here"
+
+    result = @to.convert "C1@What-27s+Here"
+    assert_equal para("<a href=\"C1.html#whats-here\">What\u2019s Here at <code>C1</code></a>"), result
+  end
+
   def test_convert_CROSSREF_constant
     result = @to.convert 'C1::CONST'
 

test/rdoc/markup/to_html_test.rb

@@ -360,6 +360,56 @@ def test_accept_heading_pipe
     assert_equal "\n<h1 id=\"hello\">Hello</h1>\n", @to.res.join
   end
 
+  def test_accept_heading_duplicate
+    @to.start_accepting
+
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+
+    result = @to.res.join
+    assert_match(/<h2 id="hello">/, result)
+    assert_match(/<h2 id="hello-1">/, result)
+    assert_match(/id="label-Hello" class="legacy-anchor"/, result)
+    assert_match(/id="label-Hello-1" class="legacy-anchor"/, result)
+  end
+
+  def test_accept_heading_duplicate_punctuation_collision
+    @to.start_accepting
+
+    @to.accept_heading @RM::Heading.new(2, 'Method match')
+    @to.accept_heading @RM::Heading.new(2, 'Method match?')
+
+    result = @to.res.join
+    assert_match(/<h2 id="method-match">/, result)
+    assert_match(/<h2 id="method-match-1">/, result)
+  end
+
+  def test_accept_heading_three_duplicates
+    @to.start_accepting
+
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+
+    result = @to.res.join
+    assert_match(/<h2 id="hello">/, result)
+    assert_match(/<h2 id="hello-1">/, result)
+    assert_match(/<h2 id="hello-2">/, result)
+  end
+
+  def test_accept_heading_dedup_resets_on_start_accepting
+    @to.start_accepting
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+
+    @to.start_accepting
+    @to.accept_heading @RM::Heading.new(2, 'Hello')
+
+    result = @to.res.join
+    assert_match(/<h2 id="hello">/, result)
+    refute_match(/id="hello-1"/, result)
+  end
+
   def test_accept_paragraph_newline
     hellos = ["hello", "\u{393 3b5 3b9 3ac} \u{3c3 3bf 3c5}"]
     worlds = ["world", "\u{3ba 3cc 3c3 3bc 3bf 3c2}"]

test/rdoc/markup/to_label_test.rb

@@ -111,4 +111,37 @@ def test_convert_tt
     assert_equal 'tt', @to.convert('<tt>tt</tt>')
   end
 
+  def test_decode_legacy_label
+    # [input, expected] pairs grouped by behavior:
+    #
+    # Legacy encoded characters are decoded
+    [
+      ["What-27s+Here",  "What's Here"],   # -27 = apostrophe
+      ["Foo-3A-3ABar",   "Foo::Bar"],      # -3A = colon
+      ["a-2Bb",          "a+b"],           # -2B = plus sign
+      ["foo+-25W+bar",   "foo %W bar"],    # -25 = percent, + = space
+      ["foo+bar",        "foo bar"],       # + = space
+      ["Whats-Here",     "Whats-Here"],    # New-format labels pass through unchanged
+      # -4F matches the regex (first digit 0-7) but decodes to 'O' (alphanumeric),
+      # so the alphanumeric guard leaves it as literal
+      ["class-4Fther",   "class-4Fther"],
+      # Lowercase hex patterns are not decoded (CGI.escape only produces uppercase)
+      ["a-3a-test",      "a-3a-test"],
+      # -FE is outside ASCII range (0x00-0x7F), first digit must be 0-7
+      ["x-FEy",          "x-FEy"],
+    ].each do |input, expected|
+      assert_equal expected, RDoc::Text.decode_legacy_label(input),
+        "decode_legacy_label(#{input.inspect})"
+    end
+  end
+
+  def test_decode_legacy_label_round_trip
+    # Verify that legacy-encoded labels produce the same anchor as direct conversion
+    ["What's Here", "Foo::Bar", "a + b", "Hello World"].each do |heading|
+      legacy = CGI.escape(heading).gsub('%', '-').sub(/^-/, '')
+      decoded = RDoc::Text.decode_legacy_label(legacy)
+      assert_equal RDoc::Text.to_anchor(heading), RDoc::Text.to_anchor(decoded),
+        "Round-trip failed for heading: #{heading.inspect}"
+    end
+  end
 end