Fix raise/fail nil guards, root-scoped is_a?, case/when, ||=, and namespace-scope narrowing in flow-sensitive typing

[apiology]

Summary

Five related flow-sensitive-typing gaps, fixed together since they touch the same file and spec.

raise/fail-based nil guards (fixes #1254)

• The parser gem parses raise/fail as a plain :send node, not a :raise node type, so always_leaves_compound_statement? never recognized a raise-based guard and it failed to narrow, unlike an equivalent return-based guard. Fix recognizes the :send shape (no receiver, method name :raise/:fail) alongside the existing keyword-based node types.

x = maybe_nil        # String, nil
raise 'bad' unless x
x.upcase              # String

root-scoped (::-prefixed) constants in is_a? narrowing (fixes #1251)

• type_name in FlowSensitiveTyping didn't recognize the :cbase node the parser gem emits for a leading :: on a constant (::Foo parses as s(:const, s(:cbase), :Foo)), so any fully-qualified class name silently disabled is_a?-based narrowing. Fix recognizes :cbase and renders it as a leading ::, recursing normally otherwise.

x = value                    # Object, nil
raise unless x.is_a?(::Hash)
x.fetch(:k)                   # ::Hash

case/when subject narrowing (fixes #1241)

• case/when had no flow-sensitive-typing support at all -- no NodeProcessor was registered for :case nodes, so a case subject kept its full (often union) static type in every branch.
• Fix adds a CaseNode processor and FlowSensitiveTyping#process_case, narrowing the subject to the union of each when clause's constant classes, scoped to that branch body only.

case x                      # Foo, Bar
when Foo then x.foo_only    # Foo
end

x ||= value on lvars/ivars

• x ||= value only assigns when x is falsy, so a prior non-nil value should survive -- but OrasgnNode rewrote it as a plain x = value, and plain-reassignment pins union together rather than override, so the narrowed type was lost.
• Fix adds FlowSensitiveTyping#process_or_asgn, reusing the same downcast-pin machinery that already powers is_a?/nil? narrowing to exclude nil from the prior type, scoped to the rest of the enclosing closure; no @sg-ignore comments remain anywhere in this fix.
• Conservative and scoped to lvasgn/ivasgn targets -- doesn't union in the RHS type when it differs from the variable's prior non-nil type.

@x = nil     # String, nil
@x ||= compute
@x.upcase     # String

is_a?/nil? guard narrowing at file and class-body scope

• FlowSensitiveTyping#process_if extends narrowing past a guard via enclosing_compound_statement_pin.node, but the root Pin::Namespace (NodeProcessor.process, one per file) and the per-class/module Pin::Namespace (NamespaceNode) never passed node:, so that pin's node was always nil and narrowing silently never applied there -- unlike Pin::Method/Pin::Block, which already pass node:.
• Fix passes node: through at both sites, matching the existing Method/Block pattern; the gap is specific to namespace-shaped compound statements (file root, class/module bodies), not "top-level" generally -- a block at the top level already narrowed correctly. Known follow-on, not fixed here: SclassNode (class << self) has the same missing node: (unverified), and Pin::Base#combine_with/Closure#combine_with don't carry node: forward across a reopened class merged from multiple files (doesn't affect this fix, since narrowing runs before combination).

loaded = load_config          # Hash, nil
return unless loaded.is_a?(Hash)
loaded['key']                  # Hash

[apiology]

Comment drafted by Claude (Anthropic), posted on behalf of @apiology while reviewing this branch.

Found while running this branch against a real codebase: pre-existing malformed Hash{} annotations now crash the whole typecheck run

While using this branch to bulk-audit @sg-ignore comments in a downstream project, solargraph typecheck crashed partway through the workspace with:

Solargraph::ComplexTypeError: Bad hash type: name=Hash, substring=<String, nil, Enumerable<SomeClass>> - must have exactly two parameters
    unique_type.rb:69:in `parse'

Root cause is independent of this PR's own narrowing logic — it's a pre-existing type-string-generation bug in ComplexType::TypeMethods#generate_substring_from that this PR's changes happen to newly exercise (see the follow-up comment for that connection). The defect itself, reproduced directly against the library with no typecheck pipeline involved:

require "solargraph"

ct = Solargraph::ComplexType.parse("Hash{String, nil => Enumerable<Integer>}")
ut = ct.items.first
puts "hash_parameters?: #{ut.hash_parameters?}"   # => true
puts "key_types: #{ut.key_types.map(&:tag)}"      # => ["String", "nil"]
puts "subtypes: #{ut.subtypes.map(&:tag)}"        # => ["Enumerable<Integer>"]

The annotation Hash{String, nil => Enumerable<Integer>} — a Hash{} whose key type is itself an unparenthesized union (String, nil) — parses successfully, but key_types ends up with 2 entries instead of 1 (each union member wrapped as its own ComplexType). That's already surprising: all_params (key_types + subtypes) is ["String", "nil", "Enumerable<Integer>"], 3 elements, for what should be a 2-slot Hash<K, V>.

generate_substring_from (lib/solargraph/complex_type/type_methods.rb:180-203) renders correctly only while hash_parameters? is true:

elsif hash_parameters?
  "{#{key_types_str} => #{subtypes_str}}"
...
elsif name == 'Hash'
  "<#{key_types_str}, #{subtypes_str}>"

But any code path that reconstructs this type's tag string without that flag set (anything that rebuilds it via key_types/subtypes rather than reusing the original parsed object) falls into the name == 'Hash' branch — which for this type necessarily produces Hash<String, nil, Enumerable<Integer>>, a 3-parameter string. Re-parsing that string is what raises "must have exactly two parameters", since the :list-syntax branch that handles Hash<A, B> (as opposed to Hash{A => B}) hard-requires exactly 2.

I wasn't able to pin the exact live call path that loses the flag (traced it toward resolve_generics's handling of all_params, given this PR's diff to that method, but couldn't reproduce it via direct calls to resolve_generics in isolation — it degraded gracefully in my attempts rather than reproducing the 3-param string). What I can show directly, independent of any specific caller: a Hash{} type with an unparenthesized union key has key_types.length > 1, and generate_substring_from's Hash<...> fallback format is only valid when key_types.length == 1. That mismatch is a real, demonstrable bug regardless of which of the several places that read all_params/rebuild tags actually triggers it in a given codebase.

Whether that's worth hardening (e.g. generate_substring_from explicitly handling key_types.length != 1 for the Hash fallback branch, or the original :hash parse branch normalizing a multi-item key into a single unioned ComplexType instead of leaving it split) is up to you — happy to help narrow it further if useful.

[apiology]

Comment drafted by Claude (Anthropic), posted on behalf of @apiology while reviewing this branch.

Separately: no error-handling boundary around per-call type inference in TypeChecker

Related to the crash in my previous comment, but a distinct issue worth flagging on its own: whatever eventually triggers ComplexTypeError for a single bad type, the blast radius is the entire solargraph typecheck run for the whole workspace, not just the one file/line with the problem.

The full trace from the crash:

Solargraph::ComplexTypeError: Bad hash type: ... (Solargraph::ComplexTypeError)
    from complex_type.rb:711:in `finish_atom'
    from complex_type.rb:635:in `parse_type_string'
    from complex_type.rb:509:in `block in parse'
    from api_map.rb:575:in `get_method_stack'
    from source/chain/call.rb:63:in `block in resolve'
    from complex_type/type_methods.rb:245:in `each_unique_type'
    from source/chain/call.rb:61:in `resolve'
    from source/chain.rb:133:in `define'
    from source/chain.rb:163:in `infer_uncached'
    from source/chain.rb:151:in `infer'
    from type_checker.rb:344:in `block in call_problems'
    from type_checker.rb:323:in `call_problems'
    from type_checker.rb:92:in `problems'

TypeChecker#problems (type_checker.rb:87-95) is the per-file aggregator that's supposed to collect an Array<Problem> — one entry per issue, so a typecheck run degrades gracefully line-by-line. call_problems (type_checker.rb:321 onward) iterates every call node in a file and calls chain.infer(api_map, closure_pin, locals) per call with no rescue around it. Any exception raised deep inside that inference — ComplexTypeError here, but this boundary is equally open to any other unexpected internal error — propagates all the way up through problems and aborts the CLI's typecheck command entirely.

Concretely: one malformed annotation anywhere in a large codebase currently means solargraph typecheck silently stops reporting anything for every file processed after that point in the scan, with no indication to the user that this happened (no error summary, no "N files skipped" — the process just exits non-zero after printing however many diagnostics it collected before the crash). On a real project this meant several files' worth of legitimate typecheck findings looked like "0 problems" simply because the scan never reached them.

Suggest wrapping the chain.infer(...) call in call_problems (and possibly the analogous per-tag walks in method_tag_problems/variable_type_tag_problems) in a rescue Solargraph::ComplexTypeError (or StandardError more broadly) that converts it into a Problem for that specific call site — something like "internal error inferring type for this expression" — rather than letting it kill the whole run. That way a single bad annotation degrades to one reported problem instead of taking down typechecking for the rest of the project.

Happy to put up a PR for this if it'd be useful, once the exact rescue scope is agreed on.

[apiology]

Claude:

Tested this fix (58db074, "Fixes #1254") against apiology/checkoff's real @sg-ignore tool-limitation:type-narrowing markers. It only covers an if-branch whose body is exactly one raise/fail statement. A branch with more than one statement -- very commonly, computing something for the error message before raising -- still doesn't narrow:

# typed: true
# frozen_string_literal: true

class Example
  # @param s [String, nil]
  # @return [String]
  def single_statement_raise(s)
    if s.nil?
      raise 'not found'
    end
    s
  end

  # @param s [String, nil]
  # @return [String]
  def multi_statement_raise(s)
    if s.nil?
      valid = %w[a b c]
      raise "not found. Valid: #{valid.inspect}"
    end
    s
  end
end

# solargraph typecheck --level strong reports only one error, on
# multi_statement_raise -- single_statement_raise (identical shape,
# minus one extra statement before the raise) narrows correctly:
#
#   Declared return type ::String does not match inferred type
#   ::String, nil for Example#multi_statement_raise

Root cause: always_leaves_compound_statement? (lib/solargraph/parser/flow_sensitive_typing.rb:706) does:

return false unless clause_node.type == :send

A multi-statement branch body parses as a :begin node, not :send, so this returns false immediately without ever checking whether the :begin node's last child is a raise/fail call.

[apiology]

Claude:

Separately: x || raise(...) doesn't narrow at all, with or without this fix -- a different code path entirely.

# typed: true
# frozen_string_literal: true

class Example
  # @param argv [Array<String>]
  # @return [String]
  def first_arg(argv)
    argv[0] || raise('missing first argument')
  end
end

# solargraph typecheck --level strong:
#   Example#first_arg return type could not be inferred

always_leaves_compound_statement? is only invoked from if-node handling (then_clause/else_clause, flow_sensitive_typing.rb:135 and :137). A bare x || raise(...) is an :or node, not an :if node, so it never reaches that function regardless of the fix above. ||-based nil-guards appear to have no flow-sensitive-typing support at all.

[apiology]

Comment drafted by Claude (Anthropic), posted on behalf of @apiology while reviewing this branch.

Pushed fixes for both gaps identified above:

• Multi-statement raise/fail branches: apiology@c41d1a3 moves always_leaves_compound_statement? into the shared ParserGem::NodeMethods module and recurses into a :begin clause's last child before the raise/fail shape check, so if s.nil?; valid = ...; raise "..."; end narrows the same as the single-statement case.
• x || raise(...) / x ||= raise(...): apiology@58a780f fixes the root cause directly — Chain::Or#resolve was unioning the lhs type with the rhs's inferred type, and since raise/fail infer as undefined, ComplexType collapses any union containing an undefined item down to just undefined (lib/solargraph/complex_type.rb:26), which is why the whole method's return type came back uninferrable. Chain::Or now takes a rhs_never_returns: flag (computed at chain-build time via the shared raise/fail-shape check) and, when set, returns just the lhs type minus nil instead of unioning in the never-returning rhs.

Both repro cases from the comments above now type-check clean, and the full suite is green (1633 examples, 0 failures, 65 pre-existing pending — matching this PR's original baseline).