Infer method return type from YARD macros

[lekemula]

Fixes the WIP 'infers types from macros' spec — infers a method's return type from its YARD @return macro tag when signature resolution finds none:

class Foo
  # @!macro
  #   @return [$1]
  def self.bar; end
end

Foo.bar(String) # => String

AI disclaimer: I located where the fix was needed; the macro_return_type method implementation was written by AI (Claude Code).

🤖 Generated with Claude Code

[castwide]

The problem here is that the test is based on an incorrect assumption. Macros aren't transitive to method calls in the way that the test expects. A feature like that would be nice to have, but it's just not the way that YARD macros work.

The same is true of the other WIP test in clip_spec.

In both cases, the tests are also misplaced. Macros get applied to maps before inference occurs. We should probably delete both of those tests and recreate proper ones in the right place.

One piece of good news: named macros already work as expected.

# @!macro firstarg
#   Comment from firstarg
#   @return [String]
class Foo
  # @macro firstarg
  def bar klass # expanded with comment and return tag
  end
end

Foo.new.bar # inferred as String

[lekemula]

The problem here is that the test is based on an incorrect assumption.

Funny thing is that I also initially doubted, but then when I started to feel like this is an easy fix, I thought - well, why not? :D

Feel free to do with this PR as you may. Personally, I also see this as very useful in real life.

[castwide]

Feel free to do with this PR as you may. Personally, I also see this as very useful in real life.

Me too! I'm just leery of applying this feature to YARD macros because it's not the standard behavior. If we want to make it work, we'll probably need to implement a new tag.

[lekemula]

we'll probably need to implement a new tag

Makes sense. Closing this for now. Thanks for the feedback!

[castwide]

Quick update. I dug a little further into this issue and it looks like transitive inference from named macros should be feasible after all. There are other issues that need to be resolved (most notably, pin definitions falsely report the expanded return types as undefined or nil), but they look fixable.

I'll post a draft PR shortly.