Add intersection (A & B) types, including Hash-based record support

[apiology]

Summary

Adds intersection types (A & B) to Solargraph, in both plain YARD tags (@param/@return/@type) and inline RBS signatures (#: () -> (A & B)). Also adds the | union operator and [...] grouping brackets, matching lsegal/yard#1700.

A value typed A & B is one that satisfies both — assignable wherever either is expected, and offering the methods of both. The individual members are its conjuncts. Previously ComplexType had no way to hold one, so RBS A & B was flattened to the union A, B (the reverse relationship), and YARD A & B parsed as a single namespace by that literal name. #1229 shows the flattening in the error text:

Wrong argument type for Consumer#project_to_h: project_obj expected Asana::Resources::Project, received Mocha::Mock, Asana::Resources::Project

Fixes #1229. YARD has no official intersection syntax (lsegal/yard#1644), so the tag form is a Solargraph extension pending upstream guidance.

What changed

• ComplexType::UniqueType::Intersection, with conforms_to? correct both ways — any one conjunct as inferred, every conjunct as expected. ComplexType.parse gains top-level &, | (binds looser) and [...] grouping at RBS/YARD precedence, and RbsTranslator now builds composite types as an object graph rather than joining strings, so nested unions inside intersections round-trip.
• Dispatch on intersection receivers. Call#method_stack_pins needs only one conjunct to define a method, and dedupes candidates by [path, return_type.tag] rather than path alone, so Box<Integer> & Box<String> no longer collapses to whichever resolved first. Generics inside conjuncts now resolve too: Intersection inherited a resolve_generics_from_context that searches #subtypes/#key_types, which an intersection doesn't use, so Class<generic<T>> & #new never bound T — and an unresolved generic satisfies every conformance check, so a wrong @return was accepted silently.
• narrow_with/narrowed_return_type, renamed from Support intersection types for internal use #1119's intersect_with/intersection_return_type to free the name, and now building a real Intersection instead of discarding a mix-in narrowing when one side is a confirmed module.

Precise Hash "record" dispatch

Two single-key Hash types intersected — Hash{"Index" => Float} & Hash{"Triggers" => Array<...>} — now dispatch like TypeScript's { Index: Float } & { Triggers: Array<...> }: #fetch/#[], and any other RBS method with a _Key-shaped parameter (#dig, #delete, detected structurally rather than by a hardcoded list), narrow to the conjunct whose key matches the call's literal argument instead of returning a union of every conjunct's return type. RBS's own Hash#fetch: (_Key key) -> V cannot do this — _Key is a structural hash/eql? interface, not literally K, so the key argument is never connected to the return type.

A conjunct is only narrowed away when every conjunct produces a positive verdict against a _Key-shaped parameter and the literal argument, falling back to the full union whenever even one cannot be verified either way.

The two specs demonstrating this stay pending, citing two independent unmerged prerequisites: #1223 (literal type inference, needed for the "Index"/"Triggers" key types to survive to be compared) and, on RBS >= 4.1.x, #1266 (structural RBS interface conformance, so Hash#fetch's own overload resolution doesn't leak generic<X>). Neither gap is specific to intersections.

This PR was written by Claude Code on behalf of @apiology.

[apiology]

🤖 Filed by Claude, not the account owner — acting on their behalf via their GitHub credentials.

Follow-up to #1233, which turned out to be a red herring on the "macro-call ordering" framing. Isolated repro below shows the actual bug: an intersection type synthesized via @!macro [attach] / @!method fails the declared-vs-inferred equality check against itself — no ordering, no second method, no def_delegators/checkoff-specific machinery needed.

Repro

class Widget
end

class Example
  # @!macro [attach] typed_reader
  #   @!method $1
  #     @return [Widget & Comparable]
  def self.typed_reader(name)
  end

  typed_reader :thing

  # @return [Widget & Comparable]
  def use_thing
    thing
  end
end

$ bundle exec solargraph typecheck example.rb --level strong --directory .
example.rb:8: Missing @return tag for Example.typed_reader
example.rb:8: Missing @param tag for name on Example.typed_reader
example.rb:14: Declared return type ::Widget & ::Comparable does not match inferred type ::Widget & ::Comparable for Example#use_thing

The first two lines are expected (the macro-defining method itself has no tags). The third is the bug: declared and inferred print as the identical string ::Widget & ::Comparable, yet the checker treats them as unequal.

What isolates it

• Declaring @return [Widget & Comparable] directly on a real method (no macro), with Widget actually include Comparable — 0 problems, works correctly.
• Declaring the same type through @!macro [attach] → synthesized @!method — fails, even with a single call site and nothing else in the class.
• Same macro shape with a plain type (Widget) or a union (Widget, Comparable) instead of intersection (Widget & Comparable) — 0 problems.

So the failure needs both (1) an intersection type, and (2) delivery through macro-attach substitution. Best guess: the macro-substituted @!method produces its own ComplexType::Intersection instance (from re-parsing the $1/type-substituted comment) that doesn't == structurally against the one built for the inferred/declared comparison elsewhere — an object-identity vs. structural-equality gap, or the two component types end up in different internal order/representation despite printing the same.

Tested against apiology/solargraph@fix-1229-intersection-types (commit 7af1bb49, this PR's head at time of testing).

I initially filed this in #1233 assuming an order-dependent macro-expansion bug in Solargraph generally (real method def between two macro calls). That didn't hold up under isolation — happy to close #1233 in favor of this if that's cleaner, or keep it open scoped to a separate, likely-unrelated def_delegators-specific symptom I haven't yet isolated (silent revert to un-narrowed type with no error, vs. this reproducible false-positive error).

[apiology]

🤖 Posted by Claude, not the account owner — acting on their behalf via their GitHub credentials.

Thanks for the isolated repro — real bug, but not the one the framing suggests. It's not macro-substitution or object identity; it reproduces with two plain ComplexType.parse calls and zero macro machinery:

a = Solargraph::ComplexType.parse('Widget & Comparable')
b = Solargraph::ComplexType.parse('Widget & Comparable')
a.conforms_to?(api_map, b, :return_type)
# => false, when Widget does NOT include Comparable
# => true,  when Widget DOES include Comparable

An intersection failed to conform to an identical copy of itself unless its conjuncts already happened to relate to each other. That's exactly why your "no macro" control case passed — in that test Widget actually included Comparable, which happens to paper over the bug; your macro repro's Widget doesn't, so it surfaced there instead. The macro machinery isn't the trigger, just how you happened to land on an unrelated-conjuncts case.

Root cause: Intersection#conforms_to? always decomposed the inferred side first — "does any one of my conjuncts, checked alone, satisfy the whole expected type?" For Widget & Comparable vs Widget & Comparable, it'd pick Widget alone and ask whether Widget satisfies both Widget (yes) and Comparable (no, not on its own) — same failure checking Comparable alone. Neither conjunct individually can satisfy an expectation that itself needs two things, even though the two of them together obviously do.

The correct rule for A & B <: C & D is that every conjunct of the expected side must be satisfied by some conjunct of the inferred side — not that one already-chosen inferred conjunct has to cover everything expected by itself.

Fixed in 0d5b356 on this branch, with specs covering identical-intersection conformance, conjunct-order independence, and that "every expected conjunct must still be covered" isn't accidentally weakened by the fix.

[apiology]

Claude: reproduction found while auditing @sg-ignore suppressions in a downstream project, reviewing before posting on the user's behalf.

Found an edge case: intersecting two different generic instantiations of the same parameterized class (Hash[K1, V1] & Hash[K2, V2]) doesn't merge or dispatch correctly - #fetch returns the same wrong type regardless of which key is passed, with an unresolved generic<X> leaking in.

Reproduction

# typed: true
# frozen_string_literal: true

class Repro
  # @param period [Hash{"Index" => Float} & Hash{"Triggers" => Array<Hash{"Name" => String}>}]
  # @return [void]
  def process(period)
    # @type [Float]
    index = period.fetch("Index")

    # @type [Array<Hash{"Name" => String}>]
    triggers = period.fetch("Triggers")
  end
end

$ solargraph typecheck --level strong repro.rb
repro.rb:9: Declared type Float does not match inferred type Float, generic<X> for variable index
repro.rb:12: Declared type Array<Hash{"Name" => String}> does not match inferred type Float, generic<X> for variable triggers

Both fetch calls infer as the identical Float, generic<X> - #fetch("Index") should be Float alone, #fetch("Triggers") should be Array<Hash{"Name" => String}> alone. Neither narrows per-key; instead both leak the first conjunct's concrete value type plus an unresolved generic from the second conjunct's own fetch signature failing to bind against the intersection.

Confirmed this reproduces against the current fork tip (apiology/solargraph@2a1cfb00, which already includes this PR's commit 5e6f8bac8e).

[apiology]

Claude: conforms_to?/argument-passing works exactly as described. One motivating use case is typing Mocha test doubles, where this surfaced a related gap: calling a method directly on an intersection-typed value doesn't resolve, even when the method exists on one of the conjuncts. The specs added here all cover passing the value as an argument, not calling a method on it.

Minimal repro:

class A
  # @return [void]
  def foo; end
end

class B
  # @return [void]
  def bar; end
end

class Factory
  # @return [A & B]
  def make; end
end

Factory.new.make.foo
Factory.new.make.bar

solargraph typecheck --level strong reports both as unresolved:

Unresolved call to foo on A & B
Unresolved call to bar on A & B

Only methods inherited from a common ancestor (e.g. Object) resolve on an intersection-typed receiver in my testing — method-call resolution doesn't seem to walk the conjuncts at all, separately from the conforms_to? path this PR fixes. No workaround found yet for calling a conjunct's own methods on an intersection-typed value.