ibex 0.2.0 → 0.3.0

data/lib/ibex/normalize/diagnostics.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "set"
-
 module Ibex
   # Static grammar diagnostics used by Normalizer.
   module NormalizeDiagnostics
@@ -22,10 +20,13 @@ module Ibex
     # @rbs () -> void
     def validate_symbol_metadata
       # @type self: Normalizer
-      { display: @display_name_locations, type: @semantic_type_locations }.each do |label, locations|
+      display_locations = @display_name_locations #: Hash[String, IR::location]
+      semantic_locations = @semantic_type_locations #: Hash[String, IR::location]
+      inline_rule_names = @inline_rule_names #: Set[String]
+      { display: display_locations, type: semantic_locations }.each do |label, locations|
         locations.each do |name, location|
           fail_hash(location, "#{label} declaration references undefined symbol #{name}") unless
-            symbol(name) || parameter_template?(name) || (label == :type && @inline_rule_names.include?(name))
+            symbol(name) || parameter_template?(name) || (label == :type && inline_rule_names.include?(name))
         end
       end
     end
@@ -33,12 +34,15 @@ module Ibex
     # @rbs () -> void
     def warn_duplicate_productions
       # @type self: Normalizer
+      productions = @productions #: Array[IR::Production]
+      warnings = @warnings #: Array[IR::grammar_warning]
       seen = {} #: Hash[[Integer, Array[Integer]], Integer]
-      @productions.each do |production|
+      productions.each do |production|
         signature = [production.lhs, production.rhs] #: [Integer, Array[Integer]]
         if seen.key?(signature)
-          @warnings << { type: :duplicate_production, production: production.id, original: seen[signature],
-                         loc: production.origin[:loc] }
+          location = production.origin[:loc] #: IR::location?
+          warnings << { type: :duplicate_production, production: production.id, original: seen[signature],
+                        loc: location }
         else
           seen[signature] = production.id
         end
@@ -48,23 +52,27 @@ module Ibex
     # @rbs () -> void
     def warn_unreachable_nonterminals
       # @type self: Normalizer
+      symbols = @symbols #: Array[IR::GrammarSymbol]
+      warnings = @warnings #: Array[IR::grammar_warning]
       reachable = reachable_symbol_ids
-      @symbols.select(&:nonterminal?).each do |grammar_symbol|
-        next if reachable.include?(grammar_symbol.id) || grammar_symbol.name.start_with?("$")
+      symbols.select(&:nonterminal?).each do |grammar_symbol|
+        next if reachable.key?(grammar_symbol.id) || grammar_symbol.name.start_with?("$")
 
-        @warnings << { type: :unreachable_nonterminal, symbol: grammar_symbol.name, loc: grammar_symbol.location }
+        warnings << { type: :unreachable_nonterminal, symbol: grammar_symbol.name, loc: grammar_symbol.location }
       end
     end
 
-    # @rbs () -> Set[Integer]
+    # @rbs () -> Hash[Integer, true]
     def reachable_symbol_ids
       # @type self: Normalizer
-      starts = @start_names.map { |name| required_symbol(name).id }
-      reachable = Set.new(starts)
+      start_names = @start_names #: Array[String]
+      productions = @productions #: Array[IR::Production]
+      starts = start_names.map { |name| required_symbol(name).id }
+      reachable = starts.to_h { |id| [id, true] } #: Hash[Integer, true]
       loop do
         before = reachable.length
-        @productions.select { |production| reachable.include?(production.lhs) }.each do |production|
-          production.rhs.each { |id| reachable << id }
+        productions.select { |production| reachable.key?(production.lhs) }.each do |production|
+          production.rhs.each { |id| reachable[id] = true }
         end
         return reachable if reachable.length == before
       end
@@ -73,66 +81,83 @@ module Ibex
     # @rbs () -> void
     def warn_unused_terminals
       # @type self: Normalizer
-      used = @productions.flat_map(&:rhs).to_set
-      @symbols.select(&:terminal?).each do |grammar_symbol|
-        next if grammar_symbol.reserved || used.include?(grammar_symbol.id) || @precedence.key?(grammar_symbol.name)
-
-        @warnings << { type: :unused_terminal, symbol: grammar_symbol.name, loc: grammar_symbol.location }
+      productions = @productions #: Array[IR::Production]
+      symbols = @symbols #: Array[IR::GrammarSymbol]
+      precedence = @precedence #: Hash[String, IR::precedence]
+      warnings = @warnings #: Array[IR::grammar_warning]
+      used = productions.flat_map(&:rhs).to_h { |id| [id, true] } #: Hash[Integer, true]
+      symbols.select(&:terminal?).each do |grammar_symbol|
+        next if grammar_symbol.reserved || used.key?(grammar_symbol.id) || precedence.key?(grammar_symbol.name)
+
+        warnings << { type: :unused_terminal, symbol: grammar_symbol.name, loc: grammar_symbol.location }
       end
     end
 
     # @rbs () -> void
     def warn_unreachable_terminals
       # @type self: Normalizer
+      productions = @productions #: Array[IR::Production]
+      declared_tokens = @declared_tokens #: Hash[String, IR::location]
+      warnings = @warnings #: Array[IR::grammar_warning]
       reachable = reachable_symbol_ids
-      used = @productions.flat_map(&:rhs).to_set
-      @declared_tokens.each_key do |name|
+      used = productions.flat_map(&:rhs).to_h { |id| [id, true] } #: Hash[Integer, true]
+      declared_tokens.each_key do |name|
         grammar_symbol = required_symbol(name)
-        next unless used.include?(grammar_symbol.id)
-        next if reachable.include?(grammar_symbol.id)
+        next unless used.key?(grammar_symbol.id)
+        next if reachable.key?(grammar_symbol.id)
 
-        @warnings << { type: :unreachable_terminal, symbol: name, loc: @declared_tokens[name] }
+        warnings << { type: :unreachable_terminal, symbol: name, loc: declared_tokens[name] }
       end
     end
 
     # @rbs () -> void
     def warn_unused_precedence
       # @type self: Normalizer
-      referenced = @productions.each_with_object(Set.new) do |production, symbol_ids|
-        production.rhs.each { |id| symbol_ids << id }
-        symbol_ids << production.precedence_override if production.precedence_override
+      productions = @productions #: Array[IR::Production]
+      precedence = @precedence #: Hash[String, IR::precedence]
+      precedence_locations = @precedence_locations #: Hash[String, IR::location]
+      warnings = @warnings #: Array[IR::grammar_warning]
+      referenced = {} # @type var referenced: Hash[Integer, true]
+      productions.each do |production|
+        symbol_ids = referenced
+        production.rhs.each { |id| symbol_ids[id] = true }
+        symbol_ids[production.precedence_override] = true if production.precedence_override
       end
-      @precedence.each_key do |name|
+      precedence.each_key do |name|
         grammar_symbol = required_symbol(name)
-        next if referenced.include?(grammar_symbol.id)
+        next if referenced.key?(grammar_symbol.id)
 
-        @warnings << { type: :unused_precedence, symbol: name, loc: @precedence_locations[name] }
+        warnings << { type: :unused_precedence, symbol: name, loc: precedence_locations[name] }
       end
     end
 
     # @rbs () -> void
     def warn_empty_language
       # @type self: Normalizer
+      productions = @productions #: Array[IR::Production]
+      start_names = @start_names #: Array[String]
+      warnings = @warnings #: Array[IR::grammar_warning]
       productive = productive_terminal_ids
       loop do
         before = productive.length
-        @productions.each do |production|
-          productive << production.lhs if production.rhs.all? { |id| productive.include?(id) }
+        productions.each do |production|
+          productive[production.lhs] = true if production.rhs.all? { |id| productive.key?(id) }
         end
         break if productive.length == before
       end
-      @start_names.each do |name|
-        next if productive.include?(required_symbol(name).id)
+      start_names.each do |name|
+        next if productive.key?(required_symbol(name).id)
 
         start_symbol = required_symbol(name)
-        @warnings << { type: :empty_language, symbol: name, loc: start_symbol.location }
+        warnings << { type: :empty_language, symbol: name, loc: start_symbol.location }
       end
     end
 
-    # @rbs () -> Set[Integer]
+    # @rbs () -> Hash[Integer, true]
     def productive_terminal_ids
       # @type self: Normalizer
-      @symbols.select { |grammar_symbol| productive_terminal?(grammar_symbol) }.to_set(&:id)
+      symbols = @symbols #: Array[IR::GrammarSymbol]
+      symbols.select { |grammar_symbol| productive_terminal?(grammar_symbol) }.to_h { |symbol| [symbol.id, true] }
     end
 
     # @rbs (IR::GrammarSymbol grammar_symbol) -> bool

data/lib/ibex/normalize/expander.rb

@@ -192,7 +192,7 @@ module Ibex
       IR::Action.new(code: code, location: location.to_h)
     end
 
-    # @rbs (Symbol kind, Frontend::AST::item item) -> Hash[Symbol, untyped]
+    # @rbs (Symbol kind, Frontend::AST::item item) -> Hash[Symbol, Object?]
     def synthetic_origin(kind, item)
       # @type self: Normalizer
       { kind: :"#{kind}_expansion", expression: NormalizeExpression.render(item), loc: item.loc.to_h }
@@ -210,10 +210,11 @@ module Ibex
     #   Hash[Symbol, untyped] origin, ?String? documentation, ?IR::node_annotation? node) -> void
     def add_production(lhs_name, rhs_names, action, precedence_name, origin, documentation = nil, node = nil)
       # @type self: Normalizer
-      lhs = symbol(lhs_name) || intern(lhs_name, :nonterminal, location: origin[:loc])
-      rhs = rhs_names.map { |name| symbol(name)&.id || fail_hash(origin[:loc], "undefined symbol #{name}") }
+      location = origin[:loc] #: IR::location
+      lhs = symbol(lhs_name) || intern(lhs_name, :nonterminal, location: location)
+      rhs = rhs_names.map { |name| symbol(name)&.id || fail_hash(location, "undefined symbol #{name}") }
       precedence = precedence_name && symbol(precedence_name)
-      fail_hash(origin[:loc], "undefined precedence symbol #{precedence_name}") if precedence_name && !precedence
+      fail_hash(location, "undefined precedence symbol #{precedence_name}") if precedence_name && !precedence
       @productions << IR::Production.new(id: @productions.length, lhs: lhs.id, rhs: rhs, action: action,
                                          precedence_override: precedence&.id, origin: origin,
                                          documentation: documentation, expansion: resolved_expansion, node: node)

data/lib/ibex/normalize/expression.rb

@@ -3,13 +3,15 @@
 module Ibex
   # Deterministically renders frontend EBNF items for production origin metadata.
   module NormalizeExpression
+    # @rbs! type pending_item = String | Frontend::AST::item
+
     class << self
       # @rbs (Frontend::AST::item item) -> String
       def render(item)
-        pending = [item] #: Array[untyped]
+        pending = [item] #: Array[pending_item]
         output = [] #: Array[String]
         until pending.empty?
-          current = pending.pop
+          current = pending.pop || raise(ArgumentError, "expression stack unexpectedly empty")
           if current.is_a?(String)
             output << current
             next
@@ -22,7 +24,7 @@ module Ibex
 
       private
 
-      # @rbs (Array[untyped] pending, Frontend::AST::item item) -> void
+      # @rbs (Array[pending_item] pending, Frontend::AST::item item) -> void
       def push_render_item(pending, item)
         case item
         when Frontend::AST::SymbolReference
@@ -45,7 +47,7 @@ module Ibex
         end
       end
 
-      # @rbs (Array[untyped] pending, Frontend::AST::ParameterizedReference item) -> void
+      # @rbs (Array[pending_item] pending, Frontend::AST::ParameterizedReference item) -> void
       def push_render_parameterized_reference(pending, item)
         pending << ":#{item.named_reference}" if item.named_reference
         pending << ")"
@@ -53,7 +55,7 @@ module Ibex
         pending.push("(", item.name)
       end
 
-      # @rbs (Array[untyped] pending, Frontend::AST::Group item) -> void
+      # @rbs (Array[pending_item] pending, Frontend::AST::Group item) -> void
       def push_render_group(pending, item)
         pending << ")"
         (item.alternatives.length - 1).downto(0) do |index|
@@ -63,7 +65,7 @@ module Ibex
         pending << "("
       end
 
-      # @rbs (Array[untyped] pending, Array[Frontend::AST::item] items, String separator) -> void
+      # @rbs (Array[pending_item] pending, Array[Frontend::AST::item] items, String separator) -> void
       def push_render_items(pending, items, separator)
         (items.length - 1).downto(0) do |index|
           pending << separator if index < items.length - 1

data/lib/ibex/normalize/grammar_builder.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ibex
+  # Builds the single current Grammar IR format for every normalized source.
+  module NormalizeGrammarBuilder
+    private
+
+    # @rbs (IR::ParserContract? parser_contract) -> IR::Grammar
+    def build_grammar(parser_contract)
+      # @type self: Normalizer
+      keywords = {
+        class_name: @ast.class_name, superclass: @ast.superclass, start: @start_name,
+        expect: @expected_conflicts, options: @options, symbols: @symbols,
+        mode: @mode, starts: @start_names, expect_rr: @expected_rr_conflicts,
+        parser_parameters: @parser_parameters, value_printers: @value_printers.values,
+        grammar_tests: @grammar_tests, lexer: normalize_lexer,
+        recovery: { sync_tokens: @recovery_sync_tokens, on_error_reduce: @on_error_reduce_groups },
+        productions: @productions, user_code: normalized_user_code,
+        conversions: @conversions, warnings: @warnings, user_code_chunks: normalized_user_code_chunks,
+        source_provenance: { file: @ast.loc.file, root: @resolution&.root_directory, byte_span: nil }
+      } #: { class_name: String, superclass: String?, start: String, expect: Integer, options: IR::grammar_options, symbols: Array[IR::GrammarSymbol], productions: Array[IR::Production], user_code: Hash[String, String], conversions: Hash[String, String], warnings: Array[IR::grammar_warning] } # rubocop:disable Layout/LineLength -- inline Steep shape mirrors the normalized builder contract.
+
+      IR::Grammar.new(**keywords, parser_contract: parser_contract || IR::ParserContract.new) # steep:ignore Ruby::InsufficientKeywordArguments
+    end
+  end
+end

data/lib/ibex/normalize/inline_expansion.rb

@@ -1,9 +1,43 @@
 # frozen_string_literal: true
+# rbs_inline: enabled
 
 module Ibex
   # Deterministically substitutes inline-rule productions before LR construction.
   # rubocop:disable Metrics/ModuleLength -- expansion, action plans, and id remapping share one invariant.
   module NormalizeInlineExpansion
+    # @rbs!
+    #   type inline_reference = [:physical | :step, Integer]
+    #   type inline_step = {
+    #     kind: :inline | :rule,
+    #     rule: String?,
+    #     code: String?,
+    #     loc: IR::location,
+    #     named_refs: Array[IR::named_ref],
+    #     context_length: Integer,
+    #     inputs: Array[inline_reference],
+    #     stack_inputs: Array[inline_reference],
+    #     lookahead: Integer,
+    #     result_var: bool,
+    #     result_type: String?
+    #   }
+    #   type inline_variant = {
+    #     rhs: Array[Integer],
+    #     steps: Array[inline_step],
+    #     logical_refs: Array[inline_reference],
+    #     output_ref: inline_reference?,
+    #     inline_used: bool,
+    #     inline_rule: String?,
+    #     precedence_override: Integer?,
+    #     precedence_contributes: bool,
+    #     parameter: IR::parameter_expansion?
+    #   }
+    #   type inline_frame = {
+    #     production: IR::Production,
+    #     symbol_id: Integer?,
+    #     index: Integer,
+    #     variant: inline_variant
+    #   }
+
     private
 
     # @rbs () -> void
@@ -33,20 +67,21 @@ module Ibex
     # The single-definition path reuses its accumulated arrays, so a long
     # acyclic chain remains linear in the size of its final action plan.
     # @rbs (IR::Production production, Hash[Integer, Array[IR::Production]] definitions) ->
-    #   Array[Hash[Symbol, untyped]]
+    #   Array[inline_variant]
     def expand_inline_production(production, definitions)
       # @type self: Normalizer
-      variants = [] #: Array[Hash[Symbol, untyped]]
-      worklist = [[inline_expansion_frame(production, nil)]] #: Array[Array[Hash[Symbol, untyped]]]
+      variants = [] #: Array[inline_variant]
+      worklist = [[inline_expansion_frame(production, nil)]] #: Array[Array[inline_frame]]
       until worklist.empty?
         frames = worklist.pop || raise(Ibex::Error, "internal inline expansion worklist underflow")
-        drain_inline_expansion_frames(frames, definitions, worklist, variants, production.origin[:loc])
+        location = production.origin[:loc] #: IR::location?
+        drain_inline_expansion_frames(frames, definitions, worklist, variants, location)
       end
       variants
     end
 
-    # @rbs (Array[Hash[Symbol, untyped]] frames, Hash[Integer, Array[IR::Production]] definitions,
-    #   Array[Array[Hash[Symbol, untyped]]] worklist, Array[Hash[Symbol, untyped]] variants,
+    # @rbs (Array[inline_frame] frames, Hash[Integer, Array[IR::Production]] definitions,
+    #   Array[Array[inline_frame]] worklist, Array[inline_variant] variants,
     #   IR::location? location) -> void
     def drain_inline_expansion_frames(frames, definitions, worklist, variants, location)
       loop do
@@ -60,8 +95,8 @@ module Ibex
       end
     end
 
-    # @rbs (Array[Hash[Symbol, untyped]] frames, Hash[Integer, Array[IR::Production]] definitions,
-    #   Array[Array[Hash[Symbol, untyped]]] worklist, Array[Hash[Symbol, untyped]] variants,
+    # @rbs (Array[inline_frame] frames, Hash[Integer, Array[IR::Production]] definitions,
+    #   Array[Array[inline_frame]] worklist, Array[inline_variant] variants,
     #   IR::location? location) -> bool
     def advance_inline_expansion_frame?(frames, definitions, worklist, variants, location)
       frame = frames.fetch(-1)
@@ -85,8 +120,8 @@ module Ibex
       true
     end
 
-    # @rbs (Array[Hash[Symbol, untyped]] frames, Array[IR::Production] choices, Integer symbol_id,
-    #   Array[Array[Hash[Symbol, untyped]]] worklist) -> void
+    # @rbs (Array[inline_frame] frames, Array[IR::Production] choices, Integer symbol_id,
+    #   Array[Array[inline_frame]] worklist) -> void
     def schedule_inline_choice_branches(frames, choices, symbol_id, worklist)
       choices.reverse_each do |choice|
         branch = clone_inline_expansion_frames(frames)
@@ -95,8 +130,8 @@ module Ibex
       end
     end
 
-    # @rbs (Array[Hash[Symbol, untyped]] frames, Array[Hash[Symbol, untyped]] variants,
-    #   Array[Array[Hash[Symbol, untyped]]] worklist, IR::location? location) -> bool
+    # @rbs (Array[inline_frame] frames, Array[inline_variant] variants,
+    #   Array[Array[inline_frame]] worklist, IR::location? location) -> bool
     def complete_inline_expansion_frame?(frames, variants, worklist, location)
       frame = frames.fetch(-1)
       current = frame.fetch(:production)
@@ -108,32 +143,34 @@ module Ibex
         return true
       end
 
-      choice = finish_inline_choice(completed, current, frame.fetch(:symbol_id))
+      symbol_id = frame.fetch(:symbol_id) || raise(Ibex::Error, "inline expansion frame is missing its symbol")
+      choice = finish_inline_choice(completed, current, symbol_id)
       parent = frames.fetch(-1)
       parent[:variant] = combine_inline_variant(parent.fetch(:variant), choice)
       false
     end
 
-    # @rbs (IR::Production production, Integer? symbol_id) -> Hash[Symbol, untyped]
+    # @rbs (IR::Production production, Integer? symbol_id) -> inline_frame
     def inline_expansion_frame(production, symbol_id)
       { production: production, symbol_id: symbol_id, index: 0, variant: empty_inline_variant(production) }
     end
 
-    # @rbs (Array[Hash[Symbol, untyped]] frames) -> Array[Hash[Symbol, untyped]]
+    # @rbs (Array[inline_frame] frames) -> Array[inline_frame]
     def clone_inline_expansion_frames(frames)
       frames.map do |frame|
         variant = frame.fetch(:variant)
-        frame.merge(
+        cloned = frame.merge(
           variant: variant.merge(
             rhs: variant.fetch(:rhs).dup,
             steps: variant.fetch(:steps).dup,
             logical_refs: variant.fetch(:logical_refs).dup
           )
         )
+        cloned #: inline_frame
       end
     end
 
-    # @rbs (IR::Production production) -> Hash[Symbol, untyped]
+    # @rbs (IR::Production production) -> inline_variant
     def empty_inline_variant(production)
       {
         rhs: [],
@@ -148,61 +185,69 @@ module Ibex
       }
     end
 
-    # @rbs (Hash[Symbol, untyped] variant, Integer symbol_id) -> Hash[Symbol, untyped]
+    # @rbs (inline_variant variant, Integer symbol_id) -> inline_variant
     def append_inline_symbol(variant, symbol_id)
       # @type self: Normalizer
       rhs = variant.fetch(:rhs)
       terminal = @symbols.fetch(symbol_id).terminal?
+      reference = [:physical, rhs.length] #: inline_reference
+      logical_refs = variant.fetch(:logical_refs) + [reference] #: Array[inline_reference]
       variant.merge(
         rhs: rhs + [symbol_id],
-        logical_refs: variant.fetch(:logical_refs) + [[:physical, rhs.length]],
+        logical_refs: logical_refs,
         precedence_override: terminal ? nil : variant[:precedence_override],
         precedence_contributes: terminal || variant.fetch(:precedence_contributes)
-      )
+      ) #: inline_variant
     end
 
-    # @rbs (Hash[Symbol, untyped] parent, Hash[Symbol, untyped] child) -> Hash[Symbol, untyped]
+    # @rbs (inline_variant parent, inline_variant child) -> inline_variant
     def combine_inline_variant(parent, child)
       physical_offset = parent.fetch(:rhs).length
       step_offset = parent.fetch(:steps).length
       steps = combined_inline_steps(parent, child, physical_offset, step_offset)
+      output_ref = child.fetch(:output_ref) || raise(Ibex::Error, "inline choice has no output reference")
+      rhs = append_inline_array(parent.fetch(:rhs), child.fetch(:rhs)) #: Array[Integer]
+      combined_steps = append_inline_array(parent.fetch(:steps), steps) #: Array[inline_step]
+      logical_refs = parent.fetch(:logical_refs) + [
+        remap_inline_reference(output_ref, physical_offset, step_offset)
+      ] #: Array[inline_reference]
       parent.merge(
-        rhs: append_inline_array(parent.fetch(:rhs), child.fetch(:rhs)),
-        steps: append_inline_array(parent.fetch(:steps), steps),
-        logical_refs: parent.fetch(:logical_refs) + [
-          remap_inline_reference(child.fetch(:output_ref), physical_offset, step_offset)
-        ],
+        rhs: rhs,
+        steps: combined_steps,
+        logical_refs: logical_refs,
         inline_used: true,
         inline_rule: parent[:inline_rule] || child[:inline_rule],
         precedence_override: combined_inline_precedence(parent, child),
         precedence_contributes: parent.fetch(:precedence_contributes) ||
           child.fetch(:precedence_contributes),
         parameter: parent[:parameter] || child[:parameter]
-      )
+      ) #: inline_variant
     end
 
-    # @rbs (Hash[Symbol, untyped] parent, Hash[Symbol, untyped] child,
-    #   Integer physical_offset, Integer step_offset) -> Array[Hash[Symbol, untyped]]
+    # @rbs (inline_variant parent, inline_variant child,
+    #   Integer physical_offset, Integer step_offset) -> Array[inline_step]
     def combined_inline_steps(parent, child, physical_offset, step_offset)
       return child.fetch(:steps) if physical_offset.zero? && step_offset.zero? && parent.fetch(:logical_refs).empty?
 
       remap_inline_steps(parent, child, physical_offset, step_offset)
     end
 
-    # @rbs (Array[untyped] left, Array[untyped] right) -> Array[untyped]
+    # The helper is shared by homogeneous integer and step arrays; callers
+    # assert the concrete element type at each use site.
+    # @rbs (Array[Object?] left, Array[Object?] right) -> Array[Object?]
     def append_inline_array(left, right)
       left.empty? ? right : left + right
     end
 
-    # @rbs (Hash[Symbol, untyped] parent, Hash[Symbol, untyped] child) -> Integer?
+    # @rbs (inline_variant parent, inline_variant child) -> Integer?
     def combined_inline_precedence(parent, child)
       return child[:precedence_override] if child.fetch(:precedence_contributes)
 
       parent[:precedence_override]
     end
 
-    # @rbs (Hash[Symbol, untyped] parent, Hash[Symbol, untyped] child,
-    #   Integer physical_offset, Integer step_offset) -> Array[Hash[Symbol, untyped]]
+    # @rbs (inline_variant parent, inline_variant child,
+    #   Integer physical_offset, Integer step_offset) -> Array[inline_step]
     def remap_inline_steps(parent, child, physical_offset, step_offset)
       child.fetch(:steps).map do |step|
         inputs = step.fetch(:inputs).map do |reference|
@@ -211,11 +256,12 @@ module Ibex
         stack_inputs = step.fetch(:stack_inputs).map do |reference|
           remap_inline_reference(reference, physical_offset, step_offset)
         end
-        step.merge(
+        remapped = step.merge(
           inputs: inputs,
           stack_inputs: parent.fetch(:logical_refs) + stack_inputs,
           lookahead: step.fetch(:lookahead) + physical_offset
         )
+        remapped #: inline_step
       end
     end
 
@@ -229,17 +275,16 @@ module Ibex
       [kind, index + (kind == :physical ? physical_offset : step_offset)]
     end
 
-    # @rbs (Hash[Symbol, untyped] variant, IR::Production production) -> Hash[Symbol, untyped]
+    # @rbs (inline_variant variant, IR::Production production) -> inline_variant
     def finish_inline_precedence(variant, production)
       explicit = production.precedence_override
       variant.merge(
         precedence_override: explicit || variant[:precedence_override],
         precedence_contributes: !explicit.nil? || variant.fetch(:precedence_contributes)
-      )
+      ) #: inline_variant
     end
 
-    # @rbs (Hash[Symbol, untyped] variant, IR::Production production, Integer symbol_id) ->
-    #   Hash[Symbol, untyped]
+    # @rbs (inline_variant variant, IR::Production production, Integer symbol_id) -> inline_variant
     def finish_inline_choice(variant, production, symbol_id)
       steps = variant.fetch(:steps)
       rule = @inline_rule_by_symbol.fetch(symbol_id)
@@ -250,18 +295,20 @@ module Ibex
         output_ref: [:step, steps.length - 1],
         inline_used: true,
         inline_rule: rule
-      )
+      ) #: inline_variant
     end
 
-    # @rbs (IR::Production production, Array[Array[Symbol | Integer]] inputs, Integer lookahead,
-    #   Symbol kind, String? rule) -> Hash[Symbol, untyped]
+    # @rbs (IR::Production production, Array[inline_reference] inputs, Integer lookahead,
+    #   :inline | :rule kind, String? rule) -> inline_step
     def inline_action_step(production, inputs, lookahead, kind, rule)
       action = production.action
+      location = action&.location || production.origin.fetch(:loc)
+      typed_location = location #: IR::location
       {
         kind: kind,
         rule: rule,
         code: action&.code,
-        loc: action&.location || production.origin.fetch(:loc),
+        loc: typed_location,
         named_refs: action&.named_refs || [],
         context_length: action&.context_length || 0,
         inputs: inputs,
@@ -272,7 +319,7 @@ module Ibex
       }
     end
 
-    # @rbs (IR::Production production, Hash[Symbol, untyped] variant, Integer id) -> IR::Production
+    # @rbs (IR::Production production, inline_variant variant, Integer id) -> IR::Production
     def composed_inline_production(production, variant, id)
       steps = variant.fetch(:steps)
       caller = inline_action_step(
@@ -288,9 +335,11 @@ module Ibex
       )
     end
 
-    # @rbs (IR::Production production, Integer physical_length, Array[Hash[Symbol, untyped]]) -> IR::Action
+    # @rbs (IR::Production production, Integer physical_length, Array[inline_step]) -> IR::Action
     def composed_inline_action(production, physical_length, steps)
       action = production.action
+      location = action&.location || production.origin.fetch(:loc)
+      typed_location = location #: IR::location
       fragments = steps.map do |step|
         { kind: step.fetch(:kind), source: inline_source_provenance(step.fetch(:loc)) }
       end
@@ -302,12 +351,12 @@ module Ibex
       } #: IR::action_composition
       IR::Action.new(
         code: action&.code || inline_implicit_code(production.rhs.length),
-        location: action&.location || production.origin.fetch(:loc),
+        location: typed_location,
         composition: composition
       )
     end
 
-    # @rbs (Hash[Symbol, untyped] step, Integer physical_length) -> Hash[Symbol, untyped]
+    # @rbs (inline_step step, Integer physical_length) -> IR::action_composition_step
     def composition_plan_step(step, physical_length)
       {
         kind: step.fetch(:kind),
@@ -345,12 +394,13 @@ module Ibex
       { file: location[:file], root: @resolution&.root_directory, byte_span: nil }
     end
 
-    # @rbs (IR::Production production, Hash[Symbol, untyped] variant) -> IR::production_expansion
+    # @rbs (IR::Production production, inline_variant variant) -> IR::production_expansion
     def inline_production_expansion(production, variant)
       existing = production.expansion
+      inline_rule = variant.fetch(:inline_rule) || raise(Ibex::Error, "inline expansion has no rule")
       {
         parameter: existing&.dig(:parameter) || variant[:parameter],
-        inline: { rule: variant.fetch(:inline_rule) },
+        inline: { rule: inline_rule },
         include_chain: existing&.dig(:include_chain) || []
       }
     end
@@ -367,7 +417,8 @@ module Ibex
     # @rbs (IR::Production production) -> void
     def charge_inline_expansion!(production)
       @inline_expansion_count += 1
-      enforce_inline_choice_limit!(@inline_expansion_count, production.origin[:loc])
+      location = production.origin[:loc] #: IR::location?
+      enforce_inline_choice_limit!(@inline_expansion_count, location)
     end
 
     # @rbs (Integer count, IR::location? location) -> void