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

[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.
• Method-call resolution on intersection-typed receivers: Call#method_stack_pins
  gives an Intersection conjunct "any one is enough" semantics (A & B <: A,
  A & B <: B) instead of requiring every conjunct to define the method the
  way a real union does, and dedupes candidate pins by [path, return_type.tag]
  instead of path alone, so same-path pins that already resolved to different,
  correct return types per conjunct (e.g. Box<Integer> & Box<String>) don't
  silently collapse into just the first one - fixing order-dependent dispatch.
• 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.

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, e.g. #dig,
#delete - detected structurally, not by a hardcoded method list) narrow to
the one conjunct whose key actually matches the call's own literal argument,
instead of returning a union of every conjunct's return type. RBS's own
Hash#fetch: (_Key key) -> V can't do this itself - _Key is a structural
hash/eql? interface, not literally K, so the key argument is never
connected to the return type by ordinary overload resolution.

Conservative by construction: a conjunct is only ever narrowed away when
every conjunct in the intersection produces a positive verdict (matched or
didn't) against a _Key-shaped parameter and the call's literal argument -
falling back to the original full-union behavior whenever even one conjunct
can't be verified one way or the other, so nothing is ever narrowed away
without positive evidence.

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

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.
• Hash record-dispatch narrowing verified both in isolation on this branch
  (falls back safely to the pre-existing union without Restore tuple/literal element inference and track reassignment (#1196) #1223/Structurally verify RBS interface-typed expectations #1266 present)
  and in a from-scratch merge of master + this branch + Restore tuple/literal element inference and track reassignment (#1196) #1223 + Structurally verify RBS interface-typed expectations #1266,
  where both previously-pending specs pass cleanly with no regressions in
  the broader suite.
• Full GitHub Actions CI matrix green (all Ruby/RBS legs, rubocop,
  regression, rails, overcommit, rbs validate, undercover,
  run_solargraph_rails_specs), aside from run_solargraph_rspec_specs
  (Plugin workflow), which is currently failing on every branch/PR in this
  repo independent of this change.

🤖 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]

Please use tagging standards in rules.rb

[apiology]

Do we need to handle mixins differently here? What's the consequence if we don't?

[apiology]

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

Status update on the open comment threads, now that CI is green on the branch again:

#1231 (comment) and #1231 (comment) (macro-attach intersection failing to conform to itself)

Root cause wasn't macro-substitution - Intersection#conforms_to? decomposed the inferred side first, so a single already-chosen conjunct had to satisfy the whole expected intersection by itself, which fails whenever the conjuncts don't already relate to each other (even inferred == expected).

Fixed entirely within this PR, commit 0d5b356. Spec: spec/complex_type/conforms_to_spec.rb, context 'when both the inferred and expected types are intersections' (4 cases: identical conjuncts, conjunct-order independence, still requires full expected coverage, wider-inferred-satisfies-narrower-expected). No other PR needed.

#1231 (comment) and #1231 (comment) (method calls on an intersection-typed receiver don't resolve at all - A & B#foo/#bar unresolved)

Root cause: Chain::Call#resolve applied real-union semantics (every alternative must define the method) straight through Intersection conjuncts too, so a method defined on only one conjunct never resolved.

Fixed entirely within this PR, commit 342b11b (Call#method_stack_pins now gives Intersection conjuncts "any one is enough" semantics instead). Specs added in spec/type_checker/levels/strong_spec.rb:

• 'resolves a call to a method defined on just one conjunct of an intersection-typed receiver (#1231)'
• 'resolves a conjunct method on an intersection-typed local variable, not just a call chain (#1231)'
• 'resolves conjunct methods on a three-way intersection'

No other PR needed - this was already fixed on the branch by the time #1231 (comment) was posted; that comment was likely tested against a fork tip that hadn't picked up commit 342b11b yet.

#1231 (comment) and #1231 (comment) (Hash{K1=>V1} & Hash{K2=>V2} record-dispatch: #fetch returns the wrong/unresolved type regardless of key)

Narrowing logic implemented within this PR: Call#method_stack_pins dedups candidate pins by [path, return_type.tag] instead of path alone (commit 7adb5db, fixes the order-dependence part), and key_verified_conjuncts/conjunct_key_verdict narrow to the one conjunct whose _Key-shaped parameter matches the call's own literal argument (commit 9a3c964, fixes the precision part - #fetch("Index") resolving to just Float instead of a union of every conjunct's return type).

Specs added in spec/type_checker/levels/strong_spec.rb (both currently pending, by design):

• 'dispatches generic methods per-conjunct when intersecting two instantiations of the same generic class (#1231)'
• 'dispatches generic methods per-conjunct regardless of conjunct order (#1231)'

Minimal PR set to un-pend them and close this out end-to-end:

1. This PR (Add intersection (A & B) types, including Hash-based record support #1231) - narrowing logic, already implemented
2. Restore tuple/literal element inference and track reassignment (#1196) #1223 - restores literal type inference; without it the literal "Index"/"Triggers" key types widen to plain String before the narrowing above ever sees them
3. Structurally verify RBS interface-typed expectations #1266 - structural RBS interface conformance; needed only on RBS >= 4.1.x, where Hash#fetch's exact-arity overload gets nominally (not structurally) rejected against Hash::_Key and falls through to an unresolved generic<X> - isolated in its own spec, 'leaks an unresolved generic<X> from Hash#fetch even with no intersection involved', confirming this is not intersection-specific

A related but genuinely separate bug surfaced along the way and was not folded into this PR: "same-class generic resolution binds to the first union/intersection member regardless of which one actually matches" reproduces on plain master with no &/| involved at all (a bare @generic class is enough). Filed as #1272, fix tracked in #1273. Spec: spec/type_checker/levels/strong_spec.rb, 'always dispatches a same-class generic method through the first union member, not #1231-specific' (also currently pending, tracking #1272/#1273 rather than this PR).

[apiology]

Claude: A common real-world use for intersection types is expressing "this mock satisfies a duck-typed interface" — e.g. a Mocha mock stubbed via define_method (invisible to static analysis) unioned with the duck type it was stubbed to satisfy, SomeMockClass & #some_method. That case doesn't work on this branch: the intersection is rejected wherever #some_method alone is expected, even though one of its two conjuncts is exactly that duck type.

# typecheck --level strong

# @param callback [#quack]
# @return [void]
def notify(callback)
end

# @param x [String & #quack]
# @return [void]
def relay(x)
  notify(x)
end

# Wrong argument type for #notify: callback expected #quack,
# received String & #quack

For comparison, @param x [#quack] alone (no intersection) typechecks clean — so the duck-type check itself works fine, and Intersection#conforms_to?'s "any one conjunct satisfies" semantics look correct on inspection. The gap looks like it's in ComplexType#conforms_to?'s early return for a duck-typed expected type (return duck_types_match?(...) if expected.duck_type?), which never calls into Intersection#conforms_to? at all — duck_types_match? collapses the inferred side to inferred.namespace for one static method lookup, and Intersection#namespace only reports the first conjunct.

[apiology]

Claude: Fixed in 8f7da39d6 (final version, on branch fix-1229-intersection-types). Confirmed the diagnosis: ComplexType#duck_types_match? checked the duck-typed expectation against inferred.namespace/#scope, which for an Intersection just delegate to the first conjunct. Added a helper (intersection_conjunct_quacks?) that instead checks each conjunct — recursively, since a conjunct can itself be an Intersection or a union — and, for a duck-typed conjunct, compares its own tag name directly instead of resolving a method stack on a synthetic namespace. Every non-intersection case is untouched, on the same get_method_stack check as before.