Add intersection (A & B), union (|), and grouping ([...]) type syntax

[apiology]

Summary

Adds real intersection type (A & B) support to Solargraph, usable 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.

Fixes #1229

Root cause

ComplexType had no representation for intersections - only comma-separated
unions - so A & B behaved like the union (A, B): assignable only where
every member independently matched, instead of assignable wherever any
one member matches (A & B <: A and A & B <: B).

What changed

• New ComplexType::UniqueType::Intersection, with conforms_to? correct on
  both sides (any one conjunct as inferred; every conjunct as expected,
  including intersection-vs-intersection).
• ComplexType.parse recognizes top-level & (intersection), | (union,
  binds looser than &), and [...] (grouping, e.g. [Foo | Bar] & Baz) -
  matching RBS/YARD precedence. Anonymous shorthand (<A>, (A), {A=>B})
  now defaults its name to Array/Array/Hash instead of parsing empty.
• RbsTranslator builds every composite RBS type (Intersection,
  Optional, Union, Tuple, generic args) as an object graph instead of
  joining strings, so nested unions inside intersections round-trip
  correctly in both directions.
• Renamed PR Support intersection types for internal use #1119's intersect_with/intersection_return_type to
  narrow_with/narrowed_return_type to avoid a naming collision with real
  intersections; narrow_with now builds an Intersection instead of
  discarding a mix-in narrowing when one side is a confirmed module.

Verified

• Issue's exact repro (Mocha::Mock & Asana::Resources::Project) passes
  solargraph typecheck --level strong; a plain Mocha::Mock still fails.
• Checked against RBS's own runtime type-checker semantics and real
  TypeScript/Steep narrowing behavior before implementing the mix-in fix.
• Full suite (1678 examples), rubocop, rbs validate, and self-typecheck
  (624 problems before and after - zero new) all clean; only the
  pre-existing spec/pin/method_spec.rb:516 failure remains, which
  reproduces identically on unmodified master.
• Full GitHub Actions CI matrix green.

🤖 Generated with Claude Code

https://claude.ai/code/session_019wfsRatLaRbxcsQ7ZVzifN

[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.

[apiology]

Claude: drafted while auditing @sg-ignore suppressions in a downstream project, reviewing before posting.

Confirming the distinct-methods-per-conjunct gap reported above still reproduces unchanged after pulling in #1273 (unrelated fix, doesn't touch this path):

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

class Caller
  def go
    Factory.new.make.foo
    Factory.new.make.bar
  end
end

$ solargraph typecheck --level strong repro.rb
repro.rb:21: Unresolved call to foo on A & B
repro.rb:22: Unresolved call to bar on A & B

Same result before and after #1273 - method lookup isn't walking to the second conjunct at all when the two conjuncts define different methods.

[apiology]

Claude: drafted while auditing @sg-ignore suppressions in a downstream project, reviewing before posting.

A second, distinct sub-case from the one above: when both conjuncts are the same generic class with different type arguments, method lookup does find a pin - #1273 changed what happens next, but not to a correct result.

Reproduction

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

Before #1273:

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

After #1273:

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

Both fetch calls infer as the identical type either way, regardless of which key is passed - #1273 changed it from picking one conjunct's resolved pin (order-dependent) to unioning every conjunct's resolved pin together, which is correct for a real union receiver but not for an intersection: #fetch("Index") should resolve to Float alone and #fetch("Triggers") to Array<Hash{"Name" => String}> alone, based on which conjunct's key type the argument actually matches. That needs dispatch logic distinct from the union case's "return everything each arm could produce."