Skip to content

Narrow Hash#[] to non-nil after key? and ||= - #1417

Draft
apiology wants to merge 44 commits into
castwide:masterfrom
apiology:narrow-hash-lookup-after-key-guard
Draft

apiology wants to merge 44 commits into
castwide:masterfrom
apiology:narrow-hash-lookup-after-key-guard

Conversation

@apiology

@apiology apiology commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

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

Problem

After a key? guard or h[k] ||= v, the same lookup is still nilable:

# @param h [Hash{String => Integer}]
# @param k [String]
def foo h, k
  return 0 unless h.key?(k)
  # Unresolved call to + on Integer, nil
  h[k] + 1
end

Code that checks for a key before indexing gets a false nil report, or has to switch to h.fetch(k).

Solution

Where h.key?(k) (or has_key?, include?, member?) is true, or after a statement h[k] ||= v, flow-sensitive typing records a new Pin::KeyLookup fact that Chain uses to drop nil from h[k] when h is a Hash whose values exclude nil.

The fact is its own pin type rather than a local variable named h[k], so it never shows up in completion or changes what h[k] defines to.

h and k must be locals, instance or class variables, attr_readers, or literals. The fact ends at a write to either, or at a call on h that can remove or rename a key (delete, clear, transform_keys!, compare_by_identity and similar).

Write tracking overlaps with #1258.

Not covered

apiology and others added 9 commits October 14, 2026 16:41
After `h.key?(k)` (or has_key?/include?/member?) is true,
FlowSensitiveTyping records a pin named "h[k]" whose type excludes
nil, over the same ranges other facts use. Chain#define resolves a
matching `[]` link to it when:

- the receiver is a Hash whose declared values exclude nil, since a
  stored nil survives the guard;
- receiver and key are variables, attr_readers or literals, which
  return the same value on a repeat read (#53 was closed for
  narrowing arbitrary argless calls);
- no assignment to a variable they read sits between guard and use.

Only the true side records a fact: a missing key can still be
answered by a default proc. Mutation through calls (h.delete(k)) is
not tracked, the same as every other flow-sensitive fact.

Three ignore markers cite castwide#1316: Array#first(n) is inferred
nilable because the first overload implicitly-returns-nil annotation
is applied to every overload.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAm8uhPDwH4Vst3uzZtHU6
The "h[k]" pin a key? guard records is a LocalVariable so that
var_at_location can find it, which also put it in the completion list
for bare words. A real local name never contains "[", so skip those.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAm8uhPDwH4Vst3uzZtHU6
A 'h.key?(k)' guard kept 'h[k]' non-nil past 'h.delete(k)', so a
lookup that can return nil was typed as present. End the fact at the
first Hash call on the same receiver that can remove a key, as it
already ends at a reassignment of 'h' or 'k'.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
'h.transform_keys!' can rename the guarded key and
'h.compare_by_identity' changes whether 'k' still matches it, so
either can leave 'h[k]' nil after a 'h.key?(k)' guard.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Take clip_at_writes, collect_writes, write_to? and
parse_receiver_chain, plus the process_facts call that clips each
pin's presences, verbatim from castwide#1258, so both PRs
carry the same write-tracking code. The key? guard rule now builds on
them: clip_at_key_writes ends the 'h[k]' fact at a write that
write_to? matches for 'h' or 'k', or at a key-removing call on 'h'.

The copied code narrows with is_a?(::Parser::AST::Node), which only
works with castwide#1258's type_name support for a leading '::', so that
hunk and its spec come along verbatim too.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
castwide#1258 adds process_call_chain right after
process_variable, where these helpers sat, so merging the two PRs
conflicted there. Placed after type_name, they merge cleanly.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Where AST children are typed precisely, as on
castwide#1240, a send's receiver is a union of literal
types and node, so recursing into it needs the is_a? check.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
castwide#1258 inserts it right after a new
process_call_chain call in process_expression, so a merge keeps both
identical insertions, anchored on either side of the method's end.
Next to write_to?, merging with castwide#1258 as it stands conflicts visibly,
and merges cleanly once castwide#1258 makes the same move.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
castwide#1258 now resolves a setter's receiver with
write_receiver, which prefixes 'self' for a chain rooted at a bare
call. Take write_to? and write_receiver verbatim from it, and build
the receiver and key chains of a key? guard with write_receiver
instead of #172's own written_words and self_rooted?, which gave the
same chains.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
apiology added a commit to apiology/solargraph that referenced this pull request Oct 16, 2026
#172 is now open on castwide as castwide#1417.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GgkyXKEZWpEFXo6ceA5MSw
After 'h[k] ||= v' as a statement, the statements that follow see
'h[k]' as non-nil until 'h' or 'k' is written or a key is removed,
reusing the key? guard fact. Class variables join locals and ivars
as hash receivers so '@@h[k] ||= []' narrows too.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GgkyXKEZWpEFXo6ceA5MSw
@apiology apiology changed the title Narrow Hash#[] to non-nil after a key? guard Narrow Hash#[] to non-nil after key? and ||= Oct 16, 2026
apiology added a commit to apiology/solargraph that referenced this pull request Oct 16, 2026
The h[k] ||= v narrowing from #183 is now part of castwide#1417.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GgkyXKEZWpEFXo6ceA5MSw
apiology added a commit to apiology/solargraph that referenced this pull request Oct 16, 2026
These clear with castwide#1259 and castwide#1417 together.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GgkyXKEZWpEFXo6ceA5MSw
apiology added a commit to apiology/solargraph that referenced this pull request Oct 16, 2026
They clear once castwide#1223 binds Hash#each block parameters and castwide#1417
narrows the ||= lookup.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GgkyXKEZWpEFXo6ceA5MSw
apiology added a commit to apiology/solargraph that referenced this pull request Oct 17, 2026
Strong typecheck keeps nil in store.macro_method_name_pins[...] after
a key? guard, because the receiver is a method and the key a method
call. castwide#1417 narrows only variables and attr_readers, and no other PR
or issue covers this shape, so label the marker with the error text.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEntZKsZwQHhzqcwG7MTqn
apiology and others added 9 commits October 17, 2026 16:53
Resolve strong_spec.rb conflict by keeping the Hash lookup specs and
the Forwardable delegation specs from master.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEntZKsZwQHhzqcwG7MTqn
parse_receiver_chain is shared verbatim with castwide#1258,
where process_call_chain walks argument-less call chains through it.
Here write_receiver resolves those chains itself, so no spec reached
the recursive branch and undercover flagged it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEntZKsZwQHhzqcwG7MTqn
The type_name support for a leading :: lets is_a?(::Parser::AST::Node)
narrow, so the two markers in SendNode#symbol_word suppress nothing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEntZKsZwQHhzqcwG7MTqn
castwide#1316 is merged on master, and CI on Ruby 3.4
reports these three markers in Chain#key_guarded_pins and
Chain#stable_links? as unneeded.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEntZKsZwQHhzqcwG7MTqn
The key guard narrowing recorded 'h[k]' as a LocalVariable named
"h[k]", and Chain rebuilt that string from its links to find it.
That made go-to-definition and signature help on 'h[k]' answer the
fake variable instead of Hash#[], let an attr_reader guard narrow a
later local of the same name, and missed 'self.table[k]' because the
two sides spelled the receiver differently.

A Pin::KeyLookup now holds the receiver and key as lists of steps
such as [:lvar, :h] or [:self_call, :table]. Chain#define resolves
'[]' as usual, and Chain drops nil from its type only when a visible
fact matches the steps of the receiver and key it resolved.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0121U2gRy7f9m4MpQd4gcCAs
Key facts no longer pass through process_facts as dotted-name pins,
so nothing in this branch creates a pin that clip_at_writes clips.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0121U2gRy7f9m4MpQd4gcCAs
The do block after 'each_unique_type.all?' left Solargraph reading
each_unique_type's void block form, so the rails typecheck could not
infer non_nil_hash?. ComplexType#to_a and UniqueType#to_a both return
Array<UniqueType>.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0121U2gRy7f9m4MpQd4gcCAs
The rails typecheck read 'value.each_unique_type' in non_nil_hash? as
its void block form and reported 'Unresolved call to any? on void'.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0121U2gRy7f9m4MpQd4gcCAs
apiology added a commit to apiology/solargraph that referenced this pull request Oct 27, 2026
9bc117e labelled castwide#1223's leftovers with each
site's verbatim error. Vince approved three mechanism labels for
them: yielded tuples not destructured into block params (14), literal
tuple index returning every element type plus nil (9), and array
literals inferring bare Array (5). Relabel those 28 markers, drop
their extra error lines, and count the labels in rules.rb.

The two type_checker.rb add_to_param_details markers keep their text:
their first error is Hash#[] nil after ||= (castwide#1417),
not a tuple.
apiology added a commit to apiology/solargraph that referenced this pull request Oct 27, 2026
9bc117e labelled castwide#1223's leftovers with each
site's verbatim error. Vince approved three mechanism labels for
them: yielded tuples not destructured into block params (14), literal
tuple index returning every element type plus nil (9), and array
literals inferring bare Array (5). Relabel those 28 markers, drop
their extra error lines, and count the labels in rules.rb.

The two type_checker.rb add_to_param_details markers keep their text:
their first error is Hash#[] nil after ||= (castwide#1417),
not a tuple.
Label each sg-ignore with the PR that resolves it, per the sg-ignore
labelling rule: castwide 1392 for the links.last calls, apiology 286
for the BigDecimal arithmetic and apiology 358 for the grep narrowing,
each verified by overlaying the PR and typechecking at strong. With
286 overlaid the type.without_nil line still reports an unresolved
call, so that error stays named on the label.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
apiology and others added 3 commits October 28, 2026 22:23
Facts matched local variables by name alone, so after
'return 0 unless h.key?(k)' a block parameter 'k' or 'h' narrowed
'h[k]' inside the block. Apply a fact only when every same-named
local in sight belongs to the fact's closure or one enclosing it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
After 'return 0 unless h.key?(k)', 'k << x' or 'k.upcase!' changes
the String k in place, so h[k] can miss. End the fact at a bang call
or a String or Array mutator on the key, as at a write to it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Chain carried seven private methods for proving 'h[k]' present. They
now live with the objects they reason about:

- Chain::Index, a Call that NodeChainer emits for a one-argument '[]'
  as it emits QCall for '&.', takes its receiver and key steps from the
  AST with Pin::KeyLookup.steps_from_node, and holds the fact matching
  and non_nil_hash? (from key_present?, key_steps_of, steps_of,
  step_of).
- Pin::KeyLookup#proves? holds proves? and non_nil_value?.

Chain#define and #infer_uncached keep their without_nil calls, through
a key_present? that asks the link.

Reading the steps from the AST tells locals from method calls without
resolving each link. Index still resolves each call step, after the
steps match a fact, to require an attr_reader, as step_of did.
@apiology
apiology marked this pull request as ready for review October 30, 2026 03:21
Parser::AST::Node#children is typed Array[self] on master but as a
union of Node, Integer, Float, Rational, Complex, String, Symbol and
nil where the ast RBS shim applies, so strong typecheck flags each
place this PR passes a raw child where a Node (or nil) is expected.

Capture receivers with 'in [::Parser::AST::Node | nil => receiver, *]'
and guard the rest with is_a?(::Parser::AST::Node). Valid ASTs always
have a Node or nil in these positions, so results do not change.
@apiology
apiology marked this pull request as draft October 30, 2026 10:43
@apiology
apiology marked this pull request as ready for review October 30, 2026 12:36
Narrowing on this branch now carries ensure_body through its is_a?
guard, so strong typecheck flags the ignore above the ensure-body
concat as unneeded.
Narrowings of hash keys and pure calls are to be recorded as
expression narrowings, alongside the variable narrowings BaseVariable
already makes. Pin::Narrowing names the interface both share:
presence, visible_at? and a subject (a variable name or expression
steps). BaseVariable includes it without behaviour change.

Pin::ExpressionNarrowing holds steps in Pin::KeyLookup format plus
[:call, :[], key] for an index, an exclude/intersection refinement, a
presence, an optional check run with an ApiMap, and KeyLookup closure
and binding-identity scoping. Nothing creates one yet; the key lookup
and pure-call narrowing work adopts it.
Keeps it clear of the attribute block that castwide#1338
extends, so the two PRs merge without conflict.
Pin::KeyLookup duplicated what Pin::ExpressionNarrowing now provides:
presence range, closure visibility, outer_binding? identity. Key
guards and h[k] ||= v now push an ExpressionNarrowing whose steps end
in [:call, :[], [key]], excluding nil, with the ||= value check as a
deferred check Proc evaluated with the ApiMap at lookup.

Chain::Index matches narrowings by steps and returns the proving one;
Chain applies it with ExpressionNarrowing#narrow instead of
without_nil. Keys are limited to literals and variable roots, the
steps ExpressionNarrowing accepts. KeyLookup is removed.
The locals FlowSensitiveTyping pushes to hold LocalVariable and
ExpressionNarrowing pins, so declare them by their shared interface.
The locals Chain#define and #infer receive include ExpressionNarrowing
pins, so declare every Chain link locals parameter as Pin::Narrowing.
Call passes only BaseVariable pins to ApiMap#var_at_location, which
needs variables.

Callers still pass Array<Pin::LocalVariable>, which Solargraph rejects
because it ignores modules a superclass includes; their sg-ignores cite
castwide#1384. Unnarrowed grep results cite
#358.
No open castwide/solargraph PR narrows Enumerable#grep results to its
class argument, so these sg-ignores quote the error they suppress.
The locals node processors build, and SourceMap, Clip and TypeChecker
pass on, hold ExpressionNarrowing pins beside variables, so declare
them as Pin::Narrowing at their source. Callers of Chain#define and
#infer then match its locals type, and the sg-ignores that cited
castwide#1384 for them are gone.

MasgnNode looks up only LocalVariable pins, and SourceMap#locate_pins
returns only variables from locals, as the narrowings are not pins a
location names.
@apiology
apiology marked this pull request as draft November 18, 2026 04:58
apiology added a commit to apiology/solargraph that referenced this pull request Nov 18, 2026
A block parameter, e.g. 'each { |k| ... }', counted as a write to the
outer 'k', ending the narrowing of 'h[k]' for the rest of the method.
The outer variable is unchanged after the block, so leave only the
block out of the presence. This also keeps key facts from
castwide#1417, which share write_to?, alive after the
block.
apiology and others added 9 commits November 18, 2026 11:10
locals holds variables and expression narrowings, so the places that
want only variables (masgn, Call#resolve, Index#stable?, completion,
SourceMap#locate_pins, TypeChecker#all_variables) each filtered it
their own way. Pin::Narrowing.variables now does it once.

Each locals tag now says what it holds: the file's variables and
expression narrowings, or those visible at that point.
A bare 'subject' on BaseVariable reads as unrelated to narrowing; the
qualified name says which interface it belongs to.
::Array<::Array> said nothing about the step shapes. Spell each one
out as a tuple with literal tags, so the checker and readers see that
a step is a variable root, an argument-less call or an index with a
literal or variable key.
It holds the same steps as ExpressionNarrowing#steps; give it that
tuple type.
module_function makes a class and an instance copy of a def. Its
body is parsed with the original Method pin as closure, so its
parameters and narrowings belong to a pin that no viewing closure
equals: Method#== compares scope and visibility. Treat Method pins
that share a node as the same closure in visibility and binding
checks.

This belongs on expression-narrowing-pin; it is here because the
repeated-call narrowing is the first to put narrowings in a
module_function body.
A single intersection_return_type invites combining narrowings by
unioning their constraints, the widening nested is_a? checks hit on
BaseVariable. ExpressionNarrowing now takes intersection_return_types,
all of which apply, and narrow intersects with each in turn.
Narrowing#narrowing_subject resolves on the grep result, so the
sg-ignore for the unresolved #steps call is no longer needed.
The list passed from the parser through SourceMap and Chain to the
type checker holds variable pins and ExpressionNarrowing facts such as
h[:k] after key?, so 'locals' misnamed it. Each element states the type
an expression has over a range of code, a variable reference being the
simplest expression, so the list becomes expression_types, the mix-in
Pin::Narrowing becomes Pin::ExpressionType and #narrowing_subject
becomes #expression. ivar- and cvar-rooted expressions fit as they are.

SourceMap#locals, #locals_at and Clip#locals return variables only, as
on master; SourceMap#expression_types, #expression_types_at and
Clip#expression_types return the whole list for inference.
Undercover flagged nodes the rename touched that specs never fully ran:

- Library#references_from's Class#new filter: spec references to
  Class#new on receivers typed Class.
- Chain::Call#process_directive: spec a non-macro directive that names
  a named macro.
- Chain#define and #infer_uncached debug-log blocks: these never ran
  because LanguageServer::Host#configure lowers the shared logger level
  in an earlier spec file. spec_helper now restores DEBUG before each
  example, as it already intended.
- FlowSensitiveTyping#write_to?'s receiver-chain match: spec
  reassigning an attr_accessor through self.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LTpguFV8m5C72EvjeEFx96
apiology added a commit to apiology/solargraph that referenced this pull request Nov 18, 2026
Each pin mixing in Pin::Narrowing states the type an expression has
over a range of code, a variable reference being the simplest
expression, so the mix-in becomes Pin::ExpressionType and
#narrowing_subject becomes #expression. This matches the naming
castwide#1417 settled on.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant