ibex 0.2.0 → 0.4.0

data/lib/ibex/codegen/action_locations.rb

@@ -57,7 +57,7 @@ module Ibex
 
         offsets = line_offsets
         tokens = Object.const_get(:Ripper).__send__(:lex, lexable_source)
-        # @type var tokens: Array[[[Integer, Integer], Symbol, String, untyped]]
+        # @type var tokens: Array[[[Integer, Integer], Symbol, String, Object?]]
         tokens.filter_map do |position, type, _token, _state|
           next unless type == :on_ident
 

data/lib/ibex/codegen/action_method_source.rb

@@ -17,7 +17,7 @@ module Ibex
         @generated_action_abi = generated_action_abi || GeneratedActionABI::Cache.new
       end
 
-      # @rbs (IR::Production production, Hash[Symbol, untyped] step, Integer index) -> String
+      # @rbs (IR::Production production, IR::action_composition_step step, Integer index) -> String
       def composed_fragment_method_source(production, step, index)
         source = "private def #{composed_fragment_name(production, index)}" \
                  "(val, _values, _ibex_locations, _ibex_location_stack, _ibex_location); "
@@ -97,7 +97,7 @@ module Ibex
 
         require "ripper"
         tokens = Object.const_get(:Ripper).__send__(:lex, source)
-        # @type var tokens: Array[[[Integer, Integer], Symbol, String, untyped]]
+        # @type var tokens: Array[GeneratedActionABI::ripper_token]
         tokens.any? { |_position, event, _token, _state| event == :on_heredoc_beg }
       end
 
@@ -149,12 +149,11 @@ module Ibex
         end
       end
 
-      # @rbs (Hash[Symbol, untyped] step) -> String
+      # @rbs (IR::action_composition_step step) -> String
       def composed_semantic_code(step)
         maximum = [step.fetch(:inputs).length, step.fetch(:context_length)].max
-        ActionLocations.new(
-          step.fetch(:code), maximum: maximum, location: step.fetch(:loc)
-        ).rewrite
+        code = step.fetch(:code) #: String
+        ActionLocations.new(code, maximum: maximum, location: step.fetch(:loc)).rewrite
       end
 
       # @rbs (String source, Array[IR::named_ref] named_refs) -> void

data/lib/ibex/codegen/action_source.rb

@@ -49,7 +49,8 @@ module Ibex
       def append_value_printers(lines)
         @grammar.value_printers.each do |printer|
           symbol = @grammar.symbol(printer[:symbol]) || raise(Ibex::Error, "missing printer symbol #{printer[:symbol]}")
-          append_method(lines, printer[:loc], @method_source.value_printer_method_source(symbol.id, printer))
+          location = printer.fetch(:loc) #: IR::location
+          append_method(lines, location, @method_source.value_printer_method_source(symbol.id, printer))
         end
       end
 
@@ -83,7 +84,7 @@ module Ibex
 
       # @rbs (Array[String] lines, IR::Production production) -> void
       def append_action(lines, production)
-        location = production.action&.location || production.origin.fetch(:loc)
+        location = production.action&.location || production.origin.fetch(:loc) #: IR::location
         append_method(lines, location, @method_source.compiled_action_method_source(production))
       end
 

data/lib/ibex/codegen/ambiguity.rb

@@ -134,17 +134,18 @@ module Ibex
           @automaton, state, conflict,
           max_tokens: @max_tokens, max_configurations: @max_configurations
         )
-        result = search.call
+        outcome = search.call
+        result = outcome[:result]
         {
           state: state.id,
           type: conflict.fetch(:type).to_s,
           token: conflict.fetch(:symbol),
-          result: result ? "ambiguous" : "not_found",
+          result: outcome[:status] == :found ? "ambiguous" : "not_found",
           sentence: result ? symbol_names(result.fetch(:sentence_ids)) : [],
           lookahead_index: result&.fetch(:lookahead_index),
           interpretations: result ? result.fetch(:interpretations) : [],
-          explored_configurations: search.explored,
-          configuration_budget_exhausted: search.exhausted?
+          explored_configurations: outcome.fetch(:explored),
+          configuration_budget_exhausted: outcome.fetch(:exhausted)
         }
       end
 

data/lib/ibex/codegen/explain.rb

@@ -15,8 +15,20 @@ module Ibex
     #   type explain_entry = {
     #     state: IR::AutomatonState,
     #     conflict: IR::conflict,
-    #     example: IR::counterexample
+    #     example: LALR::search_counterexample
     #   }
+    #
+    #   type explain_token = { name: String, display_name: String?, label: String, ?query: String }
+    #   type explain_alternative = { kind: String, ?state: Integer, ?production: Integer }
+    #   type explain_search = {
+    #     status: String, explored: Integer, exhausted: bool, bounds: Hash[Symbol, Integer]
+    #   }
+    #   type explain_tree_node = {
+    #     ?symbol: explain_token, ?token: explain_token, ?production: Integer, ?children: Array[explain_tree]
+    #   }
+    #   type explain_tree = untyped
+    #   type explain_interpretation = Hash[Symbol, untyped]
+    #   type string_value = String | Integer | Symbol
 
     # Renders a selected conflict explanation from Automaton IR and counterexamples.
     # rubocop:disable Metrics/ClassLength -- inline contracts and two stable output formats stay near selection policy.
@@ -39,42 +51,50 @@ module Ibex
         @entries = select_entries
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
-        unifying = @entries.count { |entry| entry.fetch(:example).fetch(:unifying) }
+        entries = @entries #: Array[explain_entry]
+        automaton = @automaton #: IR::Automaton
+        unifying = entries.count { |entry| entry.fetch(:example).fetch(:unifying) }
+        inconclusive = entries.count { |entry| entry.fetch(:example).fetch(:inconclusive) }
         {
           ibex_explain: "conflicts",
           schema_version: SCHEMA_VERSION,
-          algorithm: @automaton.algorithm,
+          algorithm: automaton.algorithm,
           selectors: {
             state: @state_selector,
             token: @token_selector && token_reference(@token_selector, query: @token_query)
           },
           search: { max_tokens: @max_tokens, max_configurations: @max_configurations },
           summary: {
-            matched_conflicts: @entries.length,
+            matched_conflicts: entries.length,
             unifying_counterexamples: unifying,
-            nonunifying_witnesses: @entries.length - unifying
+            nonunifying_witnesses: entries.length - unifying - inconclusive,
+            inconclusive_searches: inconclusive
           },
-          conflicts: @entries.map { |entry| conflict_document(entry) }
+          conflicts: entries.map { |entry| conflict_document(entry) }
         }
       end
 
       # @rbs () -> String
       def render_text
+        automaton = @automaton #: IR::Automaton
+        entries = @entries #: Array[explain_entry]
+        state_selector = @state_selector #: Integer?
+        token_selector = @token_selector #: IR::GrammarSymbol?
         lines = [
           "Ibex conflict explanation v#{SCHEMA_VERSION}",
-          "Algorithm: #{@automaton.algorithm}",
-          "State selector: #{@state_selector || 'all'}",
-          "Token selector: #{@token_selector ? token_label(@token_selector, query: @token_query) : 'all'}",
+          "Algorithm: #{automaton.algorithm}",
+          "State selector: #{state_selector || 'all'}",
+          "Token selector: #{token_selector ? token_label(token_selector, query: @token_query) : 'all'}",
           "Search budget: #{@max_tokens} tokens, #{@max_configurations} configurations",
-          "Matched conflicts: #{@entries.length}",
+          "Matched conflicts: #{entries.length}",
           ""
         ]
-        if @entries.empty?
+        if entries.empty?
           lines << "No conflicts matched the selectors."
         else
-          @entries.each_with_index { |entry, index| append_conflict(lines, entry, index + 1) }
+          entries.each_with_index { |entry, index| append_conflict(lines, entry, index + 1) }
         end
         "#{lines.join("\n")}\n"
       end
@@ -85,10 +105,11 @@ module Ibex
       def resolve_token(query)
         return unless query
 
-        canonical = @grammar.terminals.find { |symbol| symbol.name == query }
+        grammar = @grammar #: IR::Grammar
+        canonical = grammar.terminals.find { |symbol| symbol.name == query }
         return canonical if canonical
 
-        displayed = @grammar.terminals.select { |symbol| symbol.display_name == query }
+        displayed = grammar.terminals.select { |symbol| symbol.display_name == query }
         return displayed.first if displayed.one?
 
         if displayed.length > 1
@@ -102,10 +123,12 @@ module Ibex
 
       # @rbs () -> void
       def validate_state!
-        return unless @state_selector
-        return if @state_selector >= 0 && @automaton.states.any? { |state| state.id == @state_selector }
+        state_selector = @state_selector #: Integer?
+        automaton = @automaton #: IR::Automaton
+        return unless state_selector
+        return if state_selector >= 0 && automaton.states.any? { |state| state.id == state_selector }
 
-        raise Ibex::Error, "(cli):1:1: unknown automaton state #{@state_selector}"
+        raise Ibex::Error, "(cli):1:1: unknown automaton state #{state_selector}"
       end
 
       # @rbs () -> Array[explain_entry]
@@ -113,8 +136,9 @@ module Ibex
         selections = selected_conflicts
         return [] if selections.empty?
 
+        automaton = @automaton #: IR::Automaton
         counterexamples = LALR::Counterexample.new(
-          @automaton, max_tokens: @max_tokens, max_configurations: @max_configurations
+          automaton, max_tokens: @max_tokens, max_configurations: @max_configurations
         )
         selections.map do |selection|
           state = selection.fetch(:state)
@@ -128,17 +152,20 @@ module Ibex
 
       # @rbs () -> Array[explain_selection]
       def selected_conflicts
-        @automaton.states.flat_map do |state|
+        automaton = @automaton #: IR::Automaton
+        state_selector = @state_selector #: Integer?
+        token_selector = @token_selector #: IR::GrammarSymbol?
+        automaton.states.flat_map do |state|
           state.conflicts.each_with_index.filter_map do |conflict, conflict_index|
-            next if @state_selector && state.id != @state_selector
-            next if @token_selector && conflict[:symbol] != @token_selector.name
+            next if state_selector && state.id != state_selector
+            next if token_selector && conflict[:symbol] != token_selector.name
 
             { state: state, conflict: conflict, conflict_index: conflict_index }
           end
         end
       end
 
-      # @rbs (explain_entry entry) -> Hash[Symbol, untyped]
+      # @rbs (explain_entry entry) -> Hash[Symbol, Object?]
       def conflict_document(entry)
         state = entry.fetch(:state)
         conflict = entry.fetch(:conflict)
@@ -150,69 +177,97 @@ module Ibex
           alternatives: conflict_alternatives(conflict),
           resolution: string_values(conflict.fetch(:resolution)),
           witness: {
-            kind: example.fetch(:unifying) ? "unifying_counterexample" : "nonunifying_witness",
+            kind: witness_kind(example),
             sentence: example.fetch(:sentence).map { |name| symbol_reference(name) },
             lookahead_index: example.fetch(:lookahead_index),
             symbol_path: example.fetch(:symbol_path).map { |name| symbol_reference(name) },
+            search: search_document(example.fetch(:search)),
             interpretations: example.fetch(:interpretations).map { |item| interpretation_document(item) }
           }
-        } #: Hash[Symbol, untyped]
+        } #: Hash[Symbol, Object?]
         document[:midrule_origins] = conflict[:midrule_origins] if conflict[:midrule_origins]
         document
       end
 
-      # @rbs (IR::conflict conflict) -> Array[Hash[Symbol, untyped]]
+      # @rbs (LALR::search_counterexample example) -> String
+      def witness_kind(example)
+        return "unifying_counterexample" if example.fetch(:unifying)
+        return "inconclusive" if example.fetch(:inconclusive)
+
+        "nonunifying_witness"
+      end
+
+      # @rbs (LALR::search_outcome outcome) -> explain_search
+      def search_document(outcome)
+        {
+          status: outcome.fetch(:status).to_s,
+          explored: outcome.fetch(:explored),
+          exhausted: outcome.fetch(:exhausted),
+          bounds: outcome.fetch(:bounds)
+        }
+      end
+
+      # @rbs (IR::conflict conflict) -> Array[explain_alternative]
       def conflict_alternatives(conflict)
         case conflict[:type]
         when :shift_reduce
-          [{ kind: "shift", state: conflict.fetch(:shift_to) },
-           { kind: "reduce", production: conflict.fetch(:reduce) }]
+          shift = { kind: "shift", state: conflict.fetch(:shift_to) } # @type var shift: explain_alternative
+          reduce = { kind: "reduce", production: conflict.fetch(:reduce) } # @type var reduce: explain_alternative
+          [shift, reduce]
         when :reduce_reduce
           reduce_reduce = conflict #: IR::reduce_reduce_conflict
-          reduce_reduce[:reductions].map { |production| { kind: "reduce", production: production } }
+          reduce_reduce[:reductions].map do |production|
+            { kind: "reduce", production: production }
+          end #: Array[explain_alternative]
         else
           []
         end
       end
 
-      # @rbs (IR::interpretation interpretation) -> Hash[Symbol, untyped]
+      # @rbs (IR::interpretation interpretation) -> explain_interpretation
       def interpretation_document(interpretation)
-        value = { kind: interpretation.fetch(:kind).to_s,
-                  tree: tree_document(interpretation.fetch(:tree)) } #: Hash[Symbol, untyped]
+        kind = interpretation.fetch(:kind) #: Symbol
+        tree = interpretation.fetch(:tree) #: explain_tree
+        value = { kind: kind.to_s,
+                  tree: tree_document(tree) } # @type var value: explain_interpretation
         value[:state] = interpretation[:state] if interpretation.key?(:state)
         value[:production] = interpretation[:production] if interpretation.key?(:production)
         value
       end
 
-      # @rbs (untyped tree) -> untyped
+      # @rbs (explain_tree tree) -> explain_tree
       def tree_document(tree)
         return symbol_reference(tree.to_s) unless tree.is_a?(Hash)
 
-        value = {} #: Hash[Symbol, untyped]
-        value[:symbol] = symbol_reference(tree[:symbol]) if tree[:symbol]
-        value[:token] = symbol_reference(tree[:token]) if tree[:token]
-        value[:production] = tree[:production] if tree[:production]
-        value[:children] = tree[:children].map { |child| tree_document(child) } if tree[:children]
+        node = tree #: explain_tree_node
+        value = {} # @type var value: explain_tree_node
+        value[:symbol] = symbol_reference(node[:symbol].to_s) if node[:symbol]
+        value[:token] = symbol_reference(node[:token].to_s) if node[:token]
+        value[:production] = node[:production] if node[:production]
+        value[:children] = node[:children].map { |child| tree_document(child) } if node[:children]
         value
       end
 
-      # @rbs (Hash[Symbol, untyped] value) -> Hash[Symbol, untyped]
+      # @rbs (Hash[Symbol, string_value] value) -> Hash[Symbol, string_value]
       def string_values(value)
-        value.transform_values { |item| item.is_a?(Symbol) ? item.to_s : item }
+        values = value #: Hash[Symbol, string_value]
+        values.transform_values { |item| item.is_a?(Symbol) ? item.to_s : item }
       end
 
-      # @rbs (String name) -> Hash[Symbol, untyped]
+      # @rbs (String name) -> explain_token
       def symbol_reference(name)
-        symbol = @grammar.symbol(name)
+        grammar = @grammar #: IR::Grammar
+        symbol = grammar.symbol(name)
         return { name: name, display_name: nil, label: name } unless symbol
 
         token_reference(symbol)
       end
 
-      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> Hash[Symbol, untyped]
+      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> explain_token
       def token_reference(symbol, query: nil)
+        labels = @labels #: Hash[Integer, String]
         value = { name: symbol.name, display_name: symbol.display_name,
-                  label: @labels.fetch(symbol.id, symbol.name) } #: Hash[Symbol, untyped]
+                  label: labels.fetch(symbol.id, symbol.name) } # @type var value: explain_token
         value[:query] = query if query
         value
       end
@@ -222,14 +277,18 @@ module Ibex
         state = entry.fetch(:state)
         conflict = entry.fetch(:conflict)
         example = entry.fetch(:example)
-        token = @grammar.symbol(conflict.fetch(:symbol))
+        grammar = @grammar #: IR::Grammar
+        token = grammar.symbol(conflict.fetch(:symbol))
         token_text = token ? token_label(token) : conflict.fetch(:symbol)
         type = conflict.fetch(:type).to_s.tr("_", "/")
         lines << "Conflict #{number}: state #{state.id}, #{type}, token #{token_text}"
         append_midrule_origins(lines, conflict)
         append_witness_steps(lines, state, conflict, example)
         append_interpretations(lines, example)
-        unless example.fetch(:unifying)
+        if example.fetch(:inconclusive)
+          search = example.fetch(:search)
+          lines << "  Search exhausted after #{search.fetch(:explored)} configurations; classification is inconclusive."
+        elsif !example.fetch(:unifying)
           lines << "  The search found no shared sentence within the configured budget; this witness is deterministic."
         end
         lines << ""
@@ -246,12 +305,16 @@ module Ibex
       end
 
       # @rbs (Array[String] lines, IR::AutomatonState state, IR::conflict conflict,
-      #   IR::counterexample example) -> void
+      #   LALR::search_counterexample example) -> void
       def append_witness_steps(lines, state, conflict, example)
         lines << "  1. Reach state #{state.id} with the witness prefix."
         sentence = example.fetch(:sentence).map { |name| display_name(name) }
         sentence.insert(example.fetch(:lookahead_index), "•")
-        kind = example.fetch(:unifying) ? "Unifying counterexample" : "Nonunifying reachability witness"
+        kind = case witness_kind(example)
+               when "unifying_counterexample" then "Unifying counterexample"
+               when "inconclusive" then "Inconclusive reachability witness"
+               else "Nonunifying reachability witness"
+               end
         lines << "     #{kind}: #{sentence.join(' ')}"
         lines << "  2. The lookahead permits these competing actions:"
         conflict_alternatives(conflict).each { |alternative| lines << "     - #{alternative_text(alternative)}" }
@@ -259,7 +322,7 @@ module Ibex
         lines << "  3. Resolution: #{resolution.fetch(:by)} chose #{resolution.fetch(:chose)}."
       end
 
-      # @rbs (Array[String] lines, IR::counterexample example) -> void
+      # @rbs (Array[String] lines, LALR::search_counterexample example) -> void
       def append_interpretations(lines, example)
         lines << "  Competing derivations:"
         example.fetch(:interpretations).each_with_index do |interpretation, index|
@@ -268,24 +331,25 @@ module Ibex
         end
       end
 
-      # @rbs (Hash[Symbol, untyped] alternative) -> String
+      # @rbs (explain_alternative alternative) -> String
       def alternative_text(alternative)
         return "shift to state #{alternative.fetch(:state)}" if alternative.fetch(:kind) == "shift"
 
         "reduce by production #{alternative.fetch(:production)}"
       end
 
-      # @rbs (Array[String] lines, untyped tree, String prefix, String connector) -> void
+      # @rbs (Array[String] lines, explain_tree tree, String prefix, String connector) -> void
       def append_tree(lines, tree, prefix, connector)
         unless tree.is_a?(Hash)
           lines << "#{prefix}#{connector}#{display_name(tree.to_s)}"
           return
         end
 
-        name = tree[:symbol] || tree[:token]
-        production = tree[:production] ? " (production #{tree[:production]})" : ""
+        node = tree #: explain_tree_node
+        name = node[:symbol] || node[:token]
+        production = node[:production] ? " (production #{node[:production]})" : ""
         lines << "#{prefix}#{connector}#{display_name(name.to_s)}#{production}"
-        children = tree.fetch(:children, [])
+        children = node.fetch(:children, [])
         continuation = { "" => "", "|- " => "|  " }.fetch(connector, "   ")
         child_prefix = "#{prefix}#{continuation}"
         children.each_with_index do |child, index|
@@ -305,7 +369,11 @@ module Ibex
       end
 
       # @rbs (String name) -> String
-      def display_name(name) = @grammar.symbol(name)&.then { |symbol| @labels.fetch(symbol.id, symbol.name) } || name
+      def display_name(name)
+        grammar = @grammar #: IR::Grammar
+        labels = @labels #: Hash[Integer, String]
+        grammar.symbol(name)&.then { |symbol| labels.fetch(symbol.id, symbol.name) } || name
+      end
     end
     # rubocop:enable Metrics/ClassLength
   end

data/lib/ibex/codegen/generated_action_abi.rb

@@ -9,6 +9,10 @@ module Ibex
     # action's declared inputs.
     # rubocop:disable Metrics/ModuleLength -- ABI proof and source rewriting must evolve together.
     module GeneratedActionABI
+      # @rbs!
+      #   type ripper_token = [[Integer, Integer], Symbol, String, Integer]
+      #   type sexp_value = Symbol | String | Integer | nil | Array[sexp_value]
+
       LEGACY_PARAMETERS = %w[
         _values
         _ibex_locations
@@ -148,6 +152,7 @@ module Ibex
         assignment = /\Aresult\s*=\s*(.*)\z/m.match(body)
         body = (assignment[1] || "").strip if assignment
         return false if body.empty? || body.match?(/(?<![=!<>])=(?!=|>)/)
+        return true unless body.match?(/\bval\b/)
 
         without_reads = body.gsub(/\bval\[\s*\d+\s*\]/, "")
         without_reads != body && !without_reads.match?(/\bval\b/)
@@ -188,7 +193,7 @@ module Ibex
       end
       private_class_method :simple_indexed_positional_action_source
 
-      # @rbs (Array[untyped] tokens, Array[String] parameters) -> String?
+      # @rbs (Array[ripper_token] tokens, Array[String] parameters) -> String?
       def rewrite_positional_values(tokens, parameters)
         result = [] #: Array[String]
         index = 0
@@ -219,7 +224,7 @@ module Ibex
       end
       private_class_method :rewrite_positional_values
 
-      # @rbs (Array[untyped] tokens, Integer index, Array[String] parameters) -> [String, Integer]?
+      # @rbs (Array[ripper_token] tokens, Integer index, Array[String] parameters) -> [String, Integer]?
       def positional_value_reference(tokens, index, parameters)
         return nil if receiver_before_value?(tokens, index)
 
@@ -234,7 +239,7 @@ module Ibex
       end
       private_class_method :positional_value_reference
 
-      # @rbs (Array[untyped] tokens, Integer index) -> bool
+      # @rbs (Array[ripper_token] tokens, Integer index) -> bool
       def receiver_before_value?(tokens, index)
         previous = tokens.first(index).reverse.find do |entry|
           !%i[on_sp on_nl on_ignored_nl on_comment].include?(entry[1])
@@ -257,7 +262,7 @@ module Ibex
       end
       private_class_method :references_legacy_parameter?
 
-      # @rbs (untyped node, ?untyped parent, ?Integer? child_index) -> bool
+      # @rbs (sexp_value node, ?sexp_value parent, ?Integer? child_index) -> bool
       def read_only_value_references?(node, parent = nil, child_index = nil)
         return true unless node.is_a?(Array)
         return safe_value_reference?(parent, child_index) if value_reference?(node)
@@ -274,7 +279,7 @@ module Ibex
       end
       private_class_method :value_reference?
 
-      # @rbs (untyped parent, Integer? child_index) -> bool
+      # @rbs (sexp_value? parent, Integer? child_index) -> bool
       def safe_value_reference?(parent, child_index)
         return false unless parent.is_a?(Array)
 

data/lib/ibex/codegen/rbs.rb

@@ -8,6 +8,9 @@ module Ibex
     # Generates an RBS declaration for the public surface of a generated parser.
     # rubocop:disable Metrics/ClassLength -- one generator owns the complete parser signature.
     class RBS
+      # @rbs!
+      #   type syntax_definition = { name: String, kind: Integer, fields: Hash[String, CSTMetadata::field_slot] }
+
       # @rbs @automaton: IR::Automaton
       # @rbs @grammar: IR::Grammar
       # @rbs @superclass: String
@@ -64,11 +67,11 @@ module Ibex
         lines.push("  end", "")
       end
 
-      # @rbs () -> Hash[String, Hash[Symbol, untyped]]
+      # @rbs () -> Hash[String, syntax_definition]
       def syntax_node_definitions
         metadata = CSTMetadata.new(@grammar).build
         slots = metadata.fetch(:slots)
-        definitions = {} #: Hash[String, Hash[Symbol, untyped]]
+        definitions = {} #: Hash[String, syntax_definition]
         @grammar.productions.each do |production|
           node = production.node
           next unless node
@@ -77,12 +80,13 @@ module Ibex
           name = node.fetch(:name)
           previous = definitions[name]
           fields = previous ? merge_syntax_fields(previous.fetch(:fields), slot.fetch(:fields)) : slot.fetch(:fields)
-          definitions[name] = { name: name, kind: slot.fetch(:node_kind), fields: fields }.freeze
+          definition = { name: name, kind: slot.fetch(:node_kind), fields: fields }.freeze #: syntax_definition
+          definitions[name] = definition
         end
         definitions
       end
 
-      # @rbs (Hash[String, untyped] left, Hash[String, untyped] right) -> Hash[String, untyped]
+      # @rbs (Hash[String, CSTMetadata::field_slot] left, Hash[String, CSTMetadata::field_slot] right) -> Hash[String, CSTMetadata::field_slot]
       def merge_syntax_fields(left, right)
         left.to_h do |name, left_slot|
           right_slot = right.fetch(name)
@@ -94,7 +98,7 @@ module Ibex
         end.freeze
       end
 
-      # @rbs (Array[String] lines, Hash[Symbol, untyped] definition) -> void
+      # @rbs (Array[String] lines, syntax_definition definition) -> void
       def append_syntax_node_contract(lines, definition)
         name = definition.fetch(:name)
         fields = definition.fetch(:fields)
@@ -122,17 +126,21 @@ module Ibex
         types.one? ? types.fetch(0) : "(#{types.join(' | ')})"
       end
 
-      # @rbs (Array[String] lines, Hash[String, untyped] fields) -> void
+      # @rbs (Array[String] lines, Hash[String, CSTMetadata::field_slot] fields) -> void
       def append_repetition_contracts(lines, fields)
         repeated = fields.select { |_field, slot| slot.is_a?(Hash) && slot[:extraction] }
         element = "Enumerator[Ibex::Runtime::CST::SyntaxNode | Ibex::Runtime::CST::SyntaxToken, void]"
         repeated.each do |field, slot|
+          next unless slot.is_a?(Hash)
+
           lines << "      def each_#{field}_element: () -> #{element}"
           lines << "      def each_#{field}_separator: () -> #{element}" if slot.fetch(:extraction) == :separated_list
         end
         return unless repeated.one?
 
         _field, slot = repeated.first
+        return unless slot.is_a?(Hash)
+
         lines << "      def each_element: () -> #{element}"
         lines << "      def each_separator: () -> #{element}" if slot.fetch(:extraction) == :separated_list
       end
@@ -320,7 +328,7 @@ module Ibex
         end
       end
 
-      # @rbs (IR::Production production, Hash[Symbol, untyped] plan, Integer slot, Integer step_index) -> String
+      # @rbs (IR::Production production, IR::action_composition_plan plan, Integer slot, Integer step_index) -> String
       def composition_slot_type(production, plan, slot, step_index)
         physical = plan.fetch(:physical)
         return semantic_type(production.rhs.fetch(slot)) if slot < physical