Restore tuple/literal element inference and track reassignment (#1196)

[apiology]

Summary

Restores array/tuple literal-indexed element-type inference, disabled wholesale by #1201 after specious results. Reworks tuple indexing and adds mutation/argument tracking to avoid those cases instead of giving up on precision. Fixes #1196.

• UniqueType#resolve_generics: Array/Enumerable methods (#last, #first, #each) resolve Elem to the tuple's element union, not its positional generics.
• Reassignment: index = 0; index += 1; array[index] now resolves precisely instead of the stale 0.
• tuple.rbs: literal-indexed overloads for #[]/#at/#fetch/#first restored, falling back to the element union for non-literal indices. Position-shifting mutators (#unshift, #insert, ...) widened for sound reassignment.
• Overload selection now requires an exact-literal match for literal overloads (e.g. tuple index 0), so a plain Integer falls through to the safe catch-all.
• ComplexType#without_redundant_literals drops a stale literal when its base type is already present in the union.
• TypeChecker: restarg arguments (e.g. y.push('two') on Array<Integer>) are checked against the receiver's element type.

Known limitation (documented, regression-tested): bare mutation without reassignment (array.unshift(x)) still can't be tracked.

Test plan

• Full spec suite passes (1654 examples, 0 failures)
• Rubocop / solargraph typecheck --level strong clean
• Manually verified all four repro scenarios from Specious inference in flow-sensitive typing #1196

🤖 Generated with Claude Code

https://claude.ai/code/session_014cK1bh4FZiYhuVZUt3H9L8

[castwide]

Inference is still making too many assumptions about literal values.

x = 0
x += 1
x # => inferred as 0

y = [1]
y.push 'two'
y # => inferred as Array<Integer>

I'm not sure we should make those assumptions unless a YARD tag or an RBS signature makes the intent explicit.

[apiology]

Thanks!

The first one is not what I intended for sure - that should have been handled as part of the 'track reassignment' part of the PR.

#2 should have failed as a type violation on .push() - will look into that as well.

[apiology]

Update on both examples:

Example 1 (x = 0; x += 1; x → 0, Integer) - this was never unsound: 0 is a subtype of Integer, so 0, Integer already behaved correctly, it just rendered a redundant literal (Array<1, Integer> is really just Array<Integer> - a literal in a union with its own base type adds no information). Fixed in 67bd423bd: Pin::BaseVariable#probe now drops that redundant literal when the base type is already present in the union. x now displays as Integer.

[apiology]

Example 2 (y = [1]; y.push 'two'; y → Array<Integer>, missing the pushed String): inference still can't track the mutation (documented limitation, has a regression spec), but 8e94b1cfa now catches the bad argument at the call site - y.push 'two' is flagged as expecting Integer, got String, since restarg params were previously skipped entirely by argument type checking. (Surfaced and fixed a related bug where RbsTranslator discarded restarg/kwrestarg element types entirely.) RBS itself declares push as (*E objects) -> self on Array[unchecked out E], so E is a real generic parameter - Steep, being RBS-based, resolves E against the receiver the same way we now do for the same signature. TypeScript and mypy check the pushed value against the declared element type too, though via their own type systems rather than RBS. None of them track the post-mutation container type, so that part isn't a gap unique to us.

[apiology]

Separately, edb944d5e widens the RBS return type of the tuple's position-shifting mutators (#unshift, #insert, #sort!, etc.) so the reassignment idiom is sound too:

array = [1, 'two']
array = array.unshift('zero')
array[0]  # now Integer, String, nil - was the stale, wrong Integer

Bare-statement mutation (array.unshift('zero'), no reassignment) is still the documented #1196 scenario-4 limitation - RBS's own maintainers hit and retreated from this same wall (ruby/rbs@aae95840), and our fix stays sound since we're narrowing to an already-known superset type rather than introducing a new type variable.

[apiology]

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

Bug: restarg type-check produces a blank "expected" type for bare (non-generic) per-element restargs

restarg_problems_for (added in this PR, type_checker.rb) assumes a restarg's par.return_type is always generic-wrapped (e.g. Array<Integer> for Array#push, unwrapped one level via .subtypes to get Integer). For a restarg declared with a bare per-element type in RBS — e.g. String#start_with?: (*string) -> bool — par.return_type comes back as a plain, non-generic Array with @subtypes=[]. Unwrapping that gives ComplexType.new([]), an empty type.

The return errors if ptype.nil? || ptype.undefined? guard doesn't catch this empty ComplexType, so it falls through to the error message, which renders as blank:

Wrong argument type for String#start_with?: prefixes expected , received String

(note the blank between "expected" and ",")

Reproduction

# Gemfile
gem 'solargraph', github: 'apiology/solargraph', branch: '2026-08-04'

# example.rb
# @param line [String]
# @return [Boolean]
def check(line)
  line.start_with?('x')
end

$ bundle exec solargraph typecheck example.rb --level strong
example.rb:4: Wrong argument type for String#start_with?: prefixes expected , received String
Typecheck finished in 0.045454 seconds.
1 problem found.

Confirmed via git bisect (8 steps, clean) that 8e94b1cf ("Check restarg argument types against the receiver's element type") is the first bad commit; the immediately preceding commit is clean on this same repro.

Suggested fix

Either:

• Have restarg_problems_for fall back to par.return_type itself (skipping the .subtypes unwrap) when the unwrap produces an empty type, or
• Fix ComplexType#undefined? to recognize ComplexType.new([]) (zero items) as undefined, so the existing guard catches it and bails out cleanly instead of emitting a malformed message.

Happy to help track down why RbsTranslator#to_parameter_pin produces a bare Array (rather than the real per-element type) for this specific restarg shape, if useful.

[apiology]

Bug fixed, ready for re-review, @castwide

[apiology]

Claude: Written by Claude and posted using @apiology's GitHub credentials.

On rbs 4.0.3, this branch regresses a single-argument Hash#fetch with a literal-key receiver. Merge parent 6741f7fbf is clean; the merge 771c3d02b reports Float, generic<X>. A non-literal key type (Hash{String => Float}) is a passing control. On rbs 4.1.3 this branch leaks on both arms.

# @param period [Hash{"Index" => Float}]
# @return [Float]
def literal_key(period)
  period.fetch('Index')   # => Float, generic<X>
end

I don't think this is a defect in this PR's own logic — keeping literal keys from widening to String is the point of the change. It's that doing so exposes the Hash::_Key nominal-vs-structural check described in #1231's specs, which #1266 addresses. The ask: this branch shouldn't land ahead of a _Key fix that covers rbs 4.0.x. #1231's spec guards that prerequisite as "on RBS >= 4.1.x", but our integration branch has #1266 merged and rbs 4.0.3 still leaks — so 4.0.x appears uncovered. A version-guarded pending spec here for the 4.0.x case would also make the dependency visible.

To reproduce, delete core.ser for the version under test and give each build its own SOLARGRAPH_CACHE; without SOLARGRAPH_FORCE_VERSION set, separate checkouts report the same version string and share one core-pin cache.