Add YARD macro support for DSL methods

[lekemula]

Note

AI usage disclaimer. The original implementation on my fork was hand-written by me starting in November 2024 (~18 months ago, branch lm-named-macros). The diff in this PR is a port of those 11 commits onto current master, which I produced with AI assistance because the codebase had drifted significantly in the meantime — most notably the rewrite of the YardMap class into DocMap/GemPins (#781). The original work is unchanged in intent; only the integration points were rewritten to fit the new architecture. Original 11-commit diff for reference: 524c94e9...389def6e.

Note

PR Size is not as big as it looks. Most of the lines come from the gem-with-yard-macros fixture gem for testing purpose and extracting the yard mapping directives onto their own modules/classes.

Summary

Adds support for YARD @!macro directives attached to DSL-style class methods, expanding to method/attribute/parse pins at the call sites. Works for macros declared in workspace source and in third-party gems.

Solution

The pipeline has three stages:

1. Parser stage — collect DSL call sites.
   Solargraph::Parser::ParserGem::NodeProcessors::SendNode now detects "DSL-shaped" calls (no receiver, in instance/class scope, at least one argument) and emits a Pin::Ephemeral::ClassMethodSend. The pin captures the call's name, code, comments, and arguments — arguments are pre-converted to plain Ruby values via a new simple_convert helper so macros can interpolate them as $1, $2, etc.

2. Pin stage — wrap macros as first-class objects.
   Pin::Base#collect_macros now wraps each @!macro directive in a new YardMap::Macro, which knows its method pin and exposes generate_pins_from(send_pin, source_map) to expand the macro at a call site. The existing inline directive handling in SourceMap::Mapper was extracted into per-directive modules under YardMap::Directives::* so both source-map processing and macro expansion can share the same logic.

3. ApiMap stage — match calls to macros, expand, store.
   ApiMap#process_macros runs after the bench is gathered but before the store update. It pairs every Pin::Ephemeral::ClassMethodSend with the method pin whose name it matches, expands each attached macro, and adds the generated pins to the store. Ephemeral pins are then filtered out so they don't pollute typechecking or completion.

Why ephemeral pins instead of resolving inline

The parser doesn't know whether a class-method-shaped call corresponds to a macro-decorated method — that match only happens after all pins (workspace + gems) are gathered, because macros can be defined in other files and/or gems. Emitting an ephemeral pin during parsing keeps the parser stateless, defers resolution to ApiMap#catalog, and gives gem-defined macros the same treatment as user-defined ones (the consuming workspace's parser sees the call; the gem's pin.macros are already loaded via YardMap::Mapper).

Other design points

• Gem support comes for free from YardMap::Mapper's new attached_macros index — gem yardocs that contain MacroObjects become pin.macros on the corresponding method pins, and the same process_macros loop handles them.
• Supported sub-directives inside a macro: @!method, @!attribute, @!parse. Listed in Macro::PROCESSABLE_DIRECTIVES.
• Argument-value substitution handles literals (strings, numbers, symbols, true/false), constants (resolved to their name), arrays, and hashes. Non-literal arguments fall through to Solargraph::Parser.chain so chains stay introspectable.
• Inline tags above the DSL call (e.g. # @return [Integer] written above multi_property :a, :b) are appended to each generated @!method directive's text, so per-call-site documentation overrides macro defaults.

TODOs

• Fix CI
• Test performance

🤖 Generated with Claude Code

[lekemula]

These are mainly refactored and extracted into their own "directive processors", see yard_map/directives.