rigortype 0.1.5 → 0.1.6

data/lib/rigor/inference/acceptance.rb

@@ -446,13 +446,45 @@ module Rigor
 
         def accepts_nominal_from_constant(self_type, constant, mode)
           ruby_class = resolve_class(self_type.class_name)
-          if ruby_class.nil?
-            return Type::AcceptsResult.maybe(
+          return constant_is_a_result(ruby_class, constant, self_type, mode) if ruby_class
+
+          # The host process may not have required the constant's
+          # declared self_type (e.g. `BigDecimal` since Ruby 3.4
+          # is no longer a default gem). Fall back to inspecting
+          # the value's own class ancestor chain — always loadable
+          # because the value already exists. Required for
+          # OverloadSelector to reject `Integer#+(BigDecimal) ->
+          # BigDecimal` overloads contributed by `bigdecimal`'s
+          # RBS reopening when the actual arg is a Constant<Integer>.
+          ancestor_names = constant.value.class.ancestors.map(&:name)
+          if ancestor_names.include?(self_type.class_name)
+            Type::AcceptsResult.yes(
               mode: mode,
-              reasons: "class #{self_type.class_name} not loadable; cannot prove from Constant"
+              reasons: "Constant value class ancestors include #{self_type.class_name}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Constant value class ancestors exclude #{self_type.class_name}"
             )
           end
+        end
+
+        def subtype_result_via_ancestors(actual_class, target_name, mode)
+          if actual_class.ancestors.map(&:name).include?(target_name)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "#{actual_class.name} ancestors include #{target_name}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{actual_class.name} ancestors exclude #{target_name} (target unloadable)"
+            )
+          end
+        end
 
+        def constant_is_a_result(ruby_class, constant, self_type, mode)
           if constant.value.is_a?(ruby_class)
             Type::AcceptsResult.yes(mode: mode, reasons: "Constant value is_a?(#{self_type.class_name})")
           else
@@ -794,6 +826,19 @@ module Rigor
 
           target_class = resolve_class(target_name)
           actual_class = resolve_class(actual_name)
+          # When only `actual` resolves, we can still rule out
+          # `actual <:= target` by inspecting `actual`'s ancestor
+          # chain. The canonical case: `target=BigDecimal` is not
+          # loadable in the host process (no `require` in rigor's
+          # own runtime), but `actual=Integer` IS, and Integer's
+          # ancestors do not include `BigDecimal`, so the subtype
+          # relation MUST be `:no` rather than the conservative
+          # `:maybe`. The reverse asymmetry (target resolves,
+          # actual doesn't) does not let us conclude anything —
+          # the unloaded `actual` could be an unrelated class or
+          # a subclass of `target` we can't see, so we still
+          # answer `:maybe` there.
+          return subtype_result_via_ancestors(actual_class, target_name, mode) if target_class.nil? && actual_class
           if target_class.nil? || actual_class.nil?
             return Type::AcceptsResult.maybe(
               mode: mode,

data/lib/rigor/inference/expression_typer.rb

@@ -61,6 +61,10 @@ module Rigor
         Prism::RationalNode => :type_of_literal_value,
         Prism::SymbolNode => :symbol_type_for,
         Prism::StringNode => :string_type_for,
+        Prism::XStringNode => :type_of_xstring,
+        Prism::InterpolatedXStringNode => :type_of_xstring,
+        Prism::SourceFileNode => :type_of_source_file,
+        Prism::SourceLineNode => :type_of_source_line,
         Prism::TrueNode => :type_of_true,
         Prism::FalseNode => :type_of_false,
         Prism::NilNode => :type_of_nil,
@@ -144,6 +148,9 @@ module Rigor
         Prism::AliasMethodNode => :type_of_nil_value,
         Prism::AliasGlobalVariableNode => :type_of_nil_value,
         Prism::UndefNode => :type_of_nil_value,
+        Prism::PostExecutionNode => :type_of_nil_value,
+        Prism::ShareableConstantNode => :type_of_shareable_constant,
+        Prism::ImplicitNode => :type_of_implicit,
         Prism::ForwardingSuperNode => :type_of_dynamic_top,
         Prism::BlockArgumentNode => :type_of_non_value,
         # Parameters and blocks (non-value positions)
@@ -159,6 +166,7 @@ module Rigor
         Prism::ForwardingParameterNode => :type_of_non_value,
         Prism::NoKeywordsParameterNode => :type_of_non_value,
         Prism::ImplicitRestNode => :type_of_non_value,
+        Prism::ItParametersNode => :type_of_non_value,
         Prism::BlockNode => :type_of_dynamic_top,
         Prism::SplatNode => :type_of_non_value,
         # Control flow (Slice 3 phase 1): branch types are unioned, jumps
@@ -888,6 +896,45 @@ module Rigor
         Type::Combinator.constant_of(unescaped)
       end
 
+      # Backtick (`cmd`) and `%x{cmd}` invoke Kernel#` and always return a
+      # String. Even when the content is statically known, we widen to
+      # Nominal[String] because the runtime value depends on the
+      # subprocess output, not the source text.
+      def type_of_xstring(_node)
+        Type::Combinator.nominal_of(String)
+      end
+
+      # __FILE__ is the source file path. Always non-empty when
+      # parsing a real file (the path resolver gives the buffer
+      # name, which is at minimum `"(stdin)"` / `"-e"` / a real
+      # path — never the empty String). Widened to
+      # `non-empty-string` instead of `Nominal[String]` so
+      # downstream String-emptiness checks know the value cannot
+      # be `""`.
+      def type_of_source_file(_node)
+        Type::Combinator.non_empty_string
+      end
+
+      # __LINE__ is the line of the source literal. Ruby line
+      # numbers are 1-indexed, so `__LINE__` is always at least
+      # 1 — `positive-int` (Integer in `[1, +Inf)`) is the
+      # canonical refinement.
+      def type_of_source_line(_node)
+        Type::Combinator.positive_int
+      end
+
+      # `# shareable_constant_value:` magic comment wraps the next
+      # constant write. Type is the wrapped write's value.
+      def type_of_shareable_constant(node)
+        type_of(node.write)
+      end
+
+      # `{ x: }` shorthand hash. The implicit value is the call to
+      # `x` (or a local read of `x`). Delegate.
+      def type_of_implicit(node)
+        type_of(node.value)
+      end
+
       def local_read(node)
         scope.local(node.name) || dynamic_top
       end

data/lib/rigor/inference/hkt_body.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-20 Slice 2a — node types for the parsed body of a
+    # type-function `Definition`. Each node represents one
+    # piece of a Rigor-side type expression that the reducer
+    # ({HktReducer}) walks against a concrete argument list.
+    #
+    # Slice 2a ships a programmatic constructor surface only:
+    # plugin and Rigor-bundled overlay authors build a body
+    # tree by hand using these node types. The string-grammar
+    # parser that reads `Definition#body` (the raw String slot
+    # already populated by Slice 1's `HktDirectives.parse_define`)
+    # into a tree is Slice 2b's deliverable; until it ships, the
+    # `body` String stays opaque and `body_tree` is the
+    # evaluable form.
+    #
+    # The five node types cover the JSON.parse and dry-monads
+    # use cases ADR-20 § Implementation slicing names as
+    # near-term adopters:
+    #
+    # - {TypeLeaf}    — wraps a fully-built `Rigor::Type`
+    #   (use for atoms like `nil`, `Constant<true>`,
+    #   `Nominal[Integer]`).
+    # - {Param}       — reference to a formal parameter
+    #   declared in the enclosing `Definition#params` list
+    #   (e.g. `K` in `json::value[K]`). The reducer
+    #   substitutes from the application's `args`.
+    # - {AppRef}      — abstract HKT application; the reducer
+    #   resolves it via the registry, or returns the `App`
+    #   carrier as-is when the reference is self-recursive
+    #   (lazy "tying-the-knot" handling that lets recursive
+    #   sums like `json::value` reduce without infinite
+    #   expansion).
+    # - {Union}       — N-ary union of arms.
+    # - {NominalApp}  — parameterised nominal class
+    #   (`Array[X]`, `Hash[K, V]`) whose type args are
+    #   themselves body nodes.
+    #
+    # Every node is a frozen `Data.define` value; structural
+    # equality is by-field.
+    module HktBody
+      # Wraps a pre-built `Rigor::Type` value. Use for atoms
+      # that need no substitution (e.g. `Nominal[Integer]`,
+      # `Constant<nil>`).
+      TypeLeaf = Data.define(:type) do
+        def initialize(type:)
+          raise ArgumentError, "type must not be nil" if type.nil?
+
+          super
+        end
+      end
+
+      # Reference to a formal parameter the enclosing
+      # `Definition#params` declared. The reducer substitutes
+      # this node with the matching positional arg from the
+      # `App` being reduced; an unknown name raises during
+      # reduction (the parser, when it ships, MUST reject
+      # unknown names earlier).
+      Param = Data.define(:name) do
+        def initialize(name:)
+          raise ArgumentError, "name must be a Symbol, got #{name.class}" unless name.is_a?(Symbol)
+
+          super
+        end
+      end
+
+      # Abstract HKT application — the reducer's primary
+      # recursion point. `uri` is a namespaced Symbol
+      # matching some `Registration` in the registry; `args`
+      # is an Array of body nodes (each gets substituted /
+      # resolved before being used).
+      AppRef = Data.define(:uri, :args) do
+        def initialize(uri:, args:)
+          raise ArgumentError, "uri must be a Symbol, got #{uri.class}" unless uri.is_a?(Symbol)
+          raise ArgumentError, "uri must be namespaced as `:a::b`, got #{uri.inspect}" unless uri.to_s.include?("::")
+          raise ArgumentError, "args must be an Array, got #{args.class}" unless args.is_a?(Array)
+          raise ArgumentError, "args must be non-empty" if args.empty?
+
+          super(uri: uri, args: args.dup.freeze)
+        end
+      end
+
+      # N-ary union. The reducer builds the result through
+      # `Type::Combinator.union(*reduced_arms)` so
+      # normalization (flattening, dedup, Bot drop) applies.
+      Union = Data.define(:arms) do
+        def initialize(arms:)
+          raise ArgumentError, "arms must be an Array, got #{arms.class}" unless arms.is_a?(Array)
+          raise ArgumentError, "arms must be non-empty" if arms.empty?
+
+          super(arms: arms.dup.freeze)
+        end
+      end
+
+      # Parameterised nominal class. `class_name` is the
+      # Ruby class name (`"Array"`, `"Hash"`); `args` is an
+      # Array of body nodes for the type arguments. The
+      # reducer builds the result through
+      # `Type::Combinator.nominal_of(class_name, type_args:
+      # reduced_args)`.
+      NominalApp = Data.define(:class_name, :args) do
+        def initialize(class_name:, args:)
+          unless class_name.is_a?(String) && !class_name.empty?
+            raise ArgumentError, "class_name must be a non-empty String, got #{class_name.inspect}"
+          end
+          raise ArgumentError, "args must be an Array, got #{args.class}" unless args.is_a?(Array)
+          raise ArgumentError, "args must be non-empty (use TypeLeaf with Nominal for raw class refs)" if args.empty?
+
+          super(class_name: class_name, args: args.dup.freeze)
+        end
+      end
+
+      # ADR-20 § D3 — conditional type form. `test` is a
+      # {TestSubtype} / {TestEquality} / {TestMembership}
+      # value object the reducer evaluates against the
+      # current bindings; `then_branch` / `else_branch` are
+      # body nodes. The reducer's trinary handling:
+      #
+      # - test = `yes` → return the reduced `then_branch`.
+      # - test = `no` → return the reduced `else_branch`.
+      # - test = `maybe` → widen to the union of both
+      #   reduced branches (per ADR-20 WD7 / robustness
+      #   principle).
+      Conditional = Data.define(:test, :then_branch, :else_branch) do
+        def initialize(test:, then_branch:, else_branch:)
+          raise ArgumentError, "test must not be nil" if test.nil?
+          raise ArgumentError, "then_branch must not be nil" if then_branch.nil?
+          raise ArgumentError, "else_branch must not be nil" if else_branch.nil?
+
+          super
+        end
+      end
+
+      # `left <: right` — subtype check. `left` is typically
+      # a {Param} reference; `right` is any body expression.
+      TestSubtype = Data.define(:left, :right) do
+        def initialize(left:, right:)
+          raise ArgumentError, "left/right must not be nil" if left.nil? || right.nil?
+
+          super
+        end
+      end
+
+      # `left == right` — structural equality. Useful for
+      # discriminating against literal constants
+      # (`E == :symbol`).
+      TestEquality = Data.define(:left, :right) do
+        def initialize(left:, right:)
+          raise ArgumentError, "left/right must not be nil" if left.nil? || right.nil?
+
+          super
+        end
+      end
+
+      # `left in [opt1, opt2, ...]` — set membership. Each
+      # `option` is a body node; the test passes iff `left`
+      # is structurally equal to any of the options.
+      TestMembership = Data.define(:left, :options) do
+        def initialize(left:, options:)
+          raise ArgumentError, "left must not be nil" if left.nil?
+          raise ArgumentError, "options must be an Array, got #{options.class}" unless options.is_a?(Array)
+          raise ArgumentError, "options must be non-empty" if options.empty?
+
+          super(left: left, options: options.dup.freeze)
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/hkt_body_parser.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require_relative "hkt_body"
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # ADR-20 slice 2b — parses the body of an
+    # `HktRegistry::Definition` (a `String`, as populated by
+    # Slice 1's `HktDirectives.parse_define` from
+    # `%a{rigor:v1:hkt_define}` payloads) into the `HktBody`
+    # node tree the Slice 2a reducer evaluates against.
+    #
+    # The minimum-viable grammar covered here is the
+    # union-of-atoms-and-parameterised-forms subset of ADR-20
+    # § D3 — sufficient for `JSON.parse`'s `json::value`
+    # recursive sum and for any other recursive-data-shape
+    # signatures (Lisp value trees, dry-types refinements
+    # without conditionals). The conditional / indexed-access
+    # forms (`E <: T ? A : B`, `E in [k1, k2]`) drafted in D3
+    # remain a follow-up slice — bodies that contain `?`
+    # raise `ParseError` and the calling directive parser
+    # drops the body_tree (the body String remains stored and
+    # the reducer falls back to `app.bound`).
+    #
+    # ## Grammar (slice 2b)
+    #
+    #     body         := union
+    #     union        := type_expr ("|" type_expr)*
+    #     type_expr    := atom | nominal_app | app_ref | param
+    #     atom         := "nil" | "true" | "false" | "bool" | "untyped"
+    #     param        := UCNAME   (when UCNAME ∈ params)
+    #     nominal_app  := class_name ("[" type_expr ("," type_expr)* "]")?
+    #     class_name   := "::"? UCNAME ("::" UCNAME)*
+    #     app_ref      := "App" "[" uri "," type_expr ("," type_expr)* "]"
+    #     uri          := IDENT ("::" IDENT)+
+    #     UCNAME       := /[A-Z]\w*/
+    #     IDENT        := /[a-z_]\w*/
+    #
+    # ## Disambiguation
+    #
+    # The same syntactic UCNAME spells both a parameter
+    # reference (`K` when `params = [:K]`) and a nominal class
+    # name (`Integer`). The parser resolves by checking the
+    # `params` set passed to {.parse}; an unknown UCNAME is
+    # treated as a nominal class name. `App` is reserved at
+    # the head position of an `App[...]` form; using `App` as
+    # a class name is therefore not supported.
+    #
+    # Atoms are kept verbatim as `HktBody::TypeLeaf` nodes
+    # wrapping the appropriate `Rigor::Type::*` carrier:
+    # `nil` / `true` / `false` produce `Constant` carriers;
+    # `bool` produces the `Constant<true> | Constant<false>`
+    # union; `untyped` produces `Combinator.untyped`
+    # (i.e. `Dynamic[Top]`). Nominal class names produce raw
+    # `Type::Nominal` carriers (no `name_scope` resolution at
+    # this slice — the reducer trusts the name verbatim).
+    module HktBodyParser
+      class ParseError < StandardError; end
+
+      module_function
+
+      def parse(string, params:)
+        raise ArgumentError, "string must be a String, got #{string.class}" unless string.is_a?(String)
+        raise ArgumentError, "params must be an Array, got #{params.class}" unless params.is_a?(Array)
+
+        params_set = params.to_h { |p| [p.to_sym, true] }
+        tokens = Tokenizer.new(string).tokenize
+        parser = Parser.new(tokens, params_set)
+        result = parser.parse_union
+        parser.expect_eof!
+        result
+      end
+
+      Token = Data.define(:kind, :value, :pos)
+
+      class Tokenizer
+        SCANNER_REGEX = /
+          \G
+          (?:
+            (?<ws>\s+)
+          | (?<lb>\[)
+          | (?<rb>\])
+          | (?<lparen>\()
+          | (?<rparen>\))
+          | (?<comma>,)
+          | (?<pipe>\|)
+          | (?<sub><:)
+          | (?<eq>==)
+          | (?<sep>::)
+          | (?<colon>:(?!:))
+          | (?<question>\?)
+          | (?<ident>[a-z_][a-zA-Z0-9_]*)
+          | (?<ucname>[A-Z][a-zA-Z0-9_]*)
+          )
+        /x
+
+        def initialize(string)
+          @string = string
+        end
+
+        TOKEN_KINDS = SCANNER_REGEX.named_captures.keys.freeze
+        private_constant :TOKEN_KINDS
+
+        def tokenize
+          tokens = []
+          pos = 0
+          while pos < @string.size
+            match = SCANNER_REGEX.match(@string, pos)
+            raise ParseError, "unexpected character at position #{pos}: #{@string[pos].inspect}" if match.nil?
+
+            kind = TOKEN_KINDS.find { |k| match[k] }
+            raise ParseError, "internal tokenizer error at position #{pos}" if kind.nil?
+
+            value = match[kind.to_sym]
+            raise ParseError, "internal tokenizer error: no match for #{kind}" if value.nil?
+
+            pos += value.size
+            next if kind == "ws"
+
+            tokens << Token.new(kind: kind.to_sym, value: value, pos: pos - value.size)
+          end
+          tokens
+        end
+      end
+
+      class Parser
+        def initialize(tokens, params_set)
+          @tokens = tokens
+          @pos = 0
+          @params_set = params_set
+        end
+
+        def parse_union
+          arms = [parse_type_expr]
+          while peek_kind == :pipe
+            consume
+            arms << parse_type_expr
+          end
+          return arms.first if arms.size == 1
+
+          HktBody::Union.new(arms: arms)
+        end
+
+        def parse_type_expr
+          tok = peek
+          raise ParseError, "unexpected end of input; expected type expression" if tok.nil?
+
+          case tok.kind
+          when :lparen  then parse_conditional
+          when :ident   then parse_lowercase_atom
+          when :ucname  then parse_ucname_form
+          when :sep     then parse_classname_with_leading_sep
+          else
+            raise ParseError, "unexpected token #{tok.kind} (#{tok.value.inspect}) at position #{tok.pos}"
+          end
+        end
+
+        # ADR-20 § D3 conditional parser. Grammar:
+        #
+        #     conditional := "(" test "?" union ":" union ")"
+        #     test        := type_expr ("<:" | "==") type_expr
+        #
+        # Parens delimit a conditional unambiguously — bare
+        # `(type_expr)` grouping is not supported at this slice
+        # (no use case yet). Branches can be unions; test sides
+        # are single arms (wrap in `App[my_union, ...]` if you
+        # need a union there). `in [opt1, opt2]` membership
+        # tests are programmatically supported via
+        # `HktBody::TestMembership` but the parser does not yet
+        # recognise the `in` keyword (no concrete demand yet).
+        def parse_conditional
+          expect!(:lparen)
+          test = parse_test
+          expect!(:question)
+          then_branch = parse_union
+          expect!(:colon)
+          else_branch = parse_union
+          expect!(:rparen)
+          HktBody::Conditional.new(test: test, then_branch: then_branch, else_branch: else_branch)
+        end
+
+        def parse_test
+          left = parse_type_expr
+          op = peek
+          case op&.kind
+          when :sub
+            consume
+            HktBody::TestSubtype.new(left: left, right: parse_type_expr)
+          when :eq
+            consume
+            HktBody::TestEquality.new(left: left, right: parse_type_expr)
+          when :ident
+            parse_in_membership(left, op_token: op)
+          else
+            actual = op.nil? ? "end of input" : "#{op.kind} (#{op.value.inspect})"
+            raise ParseError, "expected `<:`, `==`, or `in` in conditional test, got #{actual}"
+          end
+        end
+
+        # `left in [opt1, opt2, ...]` membership test.
+        # Distinguished from a lowercase atom by the
+        # subsequent `[` — the only place an identifier
+        # `in` is permitted at this position is membership
+        # syntax.
+        def parse_in_membership(left, op_token:)
+          unless op_token.value == "in"
+            raise ParseError,
+                  "expected `<:`, `==`, or `in` in conditional test, got ident (#{op_token.value.inspect})"
+          end
+
+          consume # in
+          expect!(:lb)
+          options = [parse_type_expr]
+          while peek_kind == :comma
+            consume
+            options << parse_type_expr
+          end
+          expect!(:rb)
+          HktBody::TestMembership.new(left: left, options: options)
+        end
+
+        def parse_lowercase_atom
+          tok = consume
+          type = case tok.value
+                 when "nil"     then Type::Constant.new(nil)
+                 when "true"    then Type::Constant.new(true)
+                 when "false"   then Type::Constant.new(false)
+                 when "bool"    then Type::Combinator.union(Type::Constant.new(true), Type::Constant.new(false))
+                 when "untyped" then Type::Combinator.untyped
+                 else raise ParseError, "unknown atom #{tok.value.inspect} at position #{tok.pos}"
+                 end
+          HktBody::TypeLeaf.new(type: type)
+        end
+
+        def parse_ucname_form
+          tok = peek
+          return parse_app_ref if tok.value == "App"
+
+          if @params_set.key?(tok.value.to_sym) && !class_continuation?
+            consume
+            return HktBody::Param.new(name: tok.value.to_sym)
+          end
+
+          parse_nominal_or_param_with_args
+        end
+
+        # Returns true when the current UCName is followed by
+        # `::` (qualified class name continuation) or `[`
+        # (parameterised application). In either case the
+        # token is a nominal, not a param ref — Slice 2b's
+        # `Param` nodes are always single bare identifiers.
+        def class_continuation?
+          next_tok = @tokens[@pos + 1]
+          next_tok && %i[sep lb].include?(next_tok.kind)
+        end
+
+        def parse_nominal_or_param_with_args
+          class_name = parse_class_name
+          if peek_kind == :lb
+            consume
+            args = parse_arg_list
+            expect!(:rb)
+            HktBody::NominalApp.new(class_name: class_name, args: args)
+          else
+            HktBody::TypeLeaf.new(type: Type::Nominal.new(class_name))
+          end
+        end
+
+        def parse_classname_with_leading_sep
+          # The leading "::" form (`::Foo::Bar`). Consume the
+          # separator so the rest threads through parse_class_name.
+          consume
+          tok = peek
+          raise ParseError, "expected class name after `::`" if tok.nil? || tok.kind != :ucname
+
+          parse_nominal_or_param_with_args
+        end
+
+        def parse_class_name
+          parts = [expect!(:ucname).value]
+          while peek_kind == :sep && @tokens[@pos + 1]&.kind == :ucname
+            consume # ::
+            parts << expect!(:ucname).value
+          end
+          parts.join("::")
+        end
+
+        def parse_app_ref
+          tok = consume
+          raise ParseError, "expected `App[...]`, got #{tok.value.inspect}" unless tok.value == "App"
+
+          expect!(:lb)
+          uri = parse_uri
+          expect!(:comma)
+          args = parse_arg_list
+          expect!(:rb)
+          HktBody::AppRef.new(uri: uri, args: args)
+        end
+
+        def parse_uri
+          parts = [expect!(:ident).value]
+          while peek_kind == :sep
+            consume
+            parts << expect!(:ident).value
+          end
+          raise ParseError, "uri must be namespaced (`a::b`), got #{parts.first.inspect}" if parts.size < 2
+
+          parts.join("::").to_sym
+        end
+
+        # Arg list for `Foo[A, B, C]` and `App[uri, A, B]`
+        # forms. Each arg is parsed as a union so per-arg
+        # `A | B` forms work (`Array[K | nil]`); the COMMA
+        # at the top level still separates args, so
+        # `Hash[K, V]` reads as two args (each a single-arm
+        # union that collapses to the arm) rather than one
+        # union of two.
+        def parse_arg_list
+          args = [parse_union]
+          while peek_kind == :comma
+            consume
+            args << parse_union
+          end
+          args
+        end
+
+        def expect_eof!
+          return if @pos >= @tokens.size
+
+          tok = @tokens[@pos]
+          raise ParseError, "expected end of input, got #{tok.kind} (#{tok.value.inspect}) at position #{tok.pos}"
+        end
+
+        private
+
+        def peek
+          @tokens[@pos]
+        end
+
+        def peek_kind
+          @tokens[@pos]&.kind
+        end
+
+        def consume
+          tok = @tokens[@pos]
+          @pos += 1
+          tok
+        end
+
+        def expect!(kind)
+          tok = @tokens[@pos]
+          if tok.nil? || tok.kind != kind
+            actual = tok.nil? ? "end of input" : "#{tok.kind} (#{tok.value.inspect})"
+            raise ParseError, "expected #{kind}, got #{actual}"
+          end
+          @pos += 1
+          tok
+        end
+      end
+    end
+  end
+end