Attach comments above annotations to constant and global declarations

[ksss]

Problem

parse_const_decl and parse_global_decl in src/parser.c did not take comment_pos. They looked up the comment only from the line of the name token. Other declarations (class, module, interface, type alias, and members) use the start of the annotations as the base line. So a comment placed above the annotations was dropped for constants and globals:

module M
  # const doc
  %a{deprecated}
  C: bool          # comment was nil (a class or def in the same layout gets it)
end

# doc
%a{deprecated}
Foo::BAR: String   # comment was nil

# doc
%a{deprecated}
$g: String         # comment was nil

Annotations were added to constants and globals in 1bc9bb4 and 075d27c. Those commits passed annotations but not comment_pos, so these two declarations never followed the rule the other declarations use.

I found this through the comments CI failure on #3242, which adds %a{deprecated} to OpenSSL::OPENSSL_FIPS. rbs annotate inserts new comments above existing annotations (Rewriter#add_comment), so it writes this layout itself. Then the parser cannot read the comment back, and rake annotate confirm_annotation is not stable.

Fix

Pass the annotation start position (annot_pos) to parse_const_decl and parse_global_decl, from both parse_decl (top level) and parse_nested_decl (class/module bodies). Then use rbs_nonnull_pos_or(comment_pos, decl_range.start) as the base line, the same as parse_type_decl.

Behavior change

A comment placed between the annotations and the name of a constant or global used to be attached. With this change it is not, which matches class, module, def, and type alias:

%a{deprecated}
# doc
FOO: String        # comment was "doc", now nil (same as class/def)

No constant or global in core/, stdlib/, or gem_rbs_collection has annotations today, so I don't know of any signature that relies on the old layout.

Verification

• New tests in test/rbs/signature_parsing_test.rb cover top-level constants, nested constants, and globals. Each test checks three layouts: comment above the annotations (attached), comment below the annotations (nil, like other declarations), and no annotation (attached). The comment-above case fails before this change.
• rake test and rake validate pass.
• rake annotate with Ruby v4.0.7 RDoc followed by git diff --exit-code core stdlib shows no diff.
• I added %a{deprecated} to OPENSSL_FIPS in a copy of stdlib/openssl/0/openssl.rbs and ran rbs annotate twice. The second run produced no change.

Related: #3246 fixes RBS::Writer dropping annotations on the same declarations.

🤖 Generated with Claude Code