ibex-runtime 0.2.0 → 0.3.0

data/lib/ibex/runtime/parser_sync_recovery.rb

@@ -10,15 +10,15 @@ module Ibex
       private_constant :ERROR_ACTION
 
       # @rbs!
-      #   private def parser_tables: () -> Hash[Symbol, untyped]
-      #   private def table_lookup: (untyped, Integer, Integer) -> untyped
-      #   private def default_action: (Integer) -> untyped
-      #   private def token_to_str: (untyped) -> String
+      #   private def parser_tables: () -> Hash[Symbol, Object?]
+      #   private def table_lookup: (Object?, Integer, Integer) -> IR::runtime_action?
+      #   private def default_action: (Integer) -> IR::runtime_action?
+      #   private def token_to_str: (Object?) -> String
       #   private def trace: (String) -> void
-      #   private def continue_recovery: () -> untyped
+      #   private def continue_recovery: () -> ([ :continue ] | [ :done, nil ])
       #   private def reject_recovery_eof: () -> [:done, nil]
-      #   private def finish_recovery: (untyped, untyped, untyped, untyped, Integer, Array[untyped],
-      #     Hash[String, untyped]?, String, Array[Proc]?) -> [:continue]
+      #   private def finish_recovery: (Object?, Object?, Object?, Object?, Integer, Array[Object?],
+      #     Hash[String, Object?]?, String, Array[Proc]?) -> [:continue]
 
       private
 
@@ -33,8 +33,8 @@ module Ibex
         !@sync_recovery_context.nil?
       end
 
-      # @rbs (Hash[Symbol, untyped] context, Hash[String, untyped]? token_data,
-      #   Array[Proc]? observers) -> untyped
+      # @rbs (Hash[Symbol, Object?] context, Hash[String, Object?]? token_data,
+      #   Array[Proc]? observers) -> ([ :continue ] | [ :done, nil ])
       def begin_sync_recovery(context, token_data, observers)
         @sync_recovery_context = context
         @sync_recovery_token_data = token_data
@@ -42,7 +42,7 @@ module Ibex
         continue_sync_recovery
       end
 
-      # @rbs () -> untyped
+      # @rbs () -> ([ :continue ] | [ :done, nil ])
       def continue_sync_recovery
         return reject_sync_recovery_eof if @lookahead == Parser::EOF_TOKEN
         return finish_sync_recovery if sync_token?(@lookahead) && synchronize_for_current_token
@@ -50,7 +50,7 @@ module Ibex
         continue_recovery
       end
 
-      # @rbs (untyped token_id) -> bool
+      # @rbs (Integer token_id) -> bool
       def sync_token?(token_id)
         tokens = parser_tables[:recovery_sync_tokens]
         tokens.is_a?(Array) && tokens.include?(token_id)
@@ -70,9 +70,10 @@ module Ibex
         end
       end
 
-      # @rbs (Integer state, Integer token_id) -> untyped
+      # @rbs (Integer state, Integer token_id) -> IR::runtime_action
       def sync_action(state, token_id)
-        return ERROR_ACTION unless parser_tables.fetch(:token_names).key?(token_id)
+        token_names = parser_tables.fetch(:token_names)
+        return ERROR_ACTION unless token_names.is_a?(Hash) && token_names.key?(token_id)
 
         table_lookup(parser_tables.fetch(:actions), state, token_id) || default_action(state) || ERROR_ACTION
       end
@@ -85,9 +86,12 @@ module Ibex
         clear_sync_recovery
         @recovery_shifts = Parser::RECOVERY_SHIFTS
         trace("recover: synchronized before #{token_to_str(@lookahead)} in state #{@state_stack.last}") if @yydebug
+        value_stack = context.fetch(:value_stack) #: Array[Object?]
+        state = context.fetch(:state) #: Integer
+        reason = context.fetch(:reason) #: String
         finish_recovery(
-          context[:token_id], context[:token_display], context[:value], context[:location], context[:state],
-          context.fetch(:value_stack), token_data, context.fetch(:reason), observers
+          context[:token_id], context[:token_display], context[:value], context[:location], state,
+          value_stack, token_data, reason, observers
         )
       end
 

data/lib/ibex/runtime/repair.rb

@@ -40,6 +40,8 @@ module Ibex
 
     # One immutable insertion, deletion, or replacement.
     class RepairEdit
+      # @rbs! type document_value = Symbol | Integer | String
+
       KINDS = %i[insert delete replace].freeze #: Array[Symbol]
 
       attr_reader :kind #: Symbol
@@ -62,7 +64,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, document_value]
       def to_h
         { kind: @kind, position: @position, token_id: @token_id, token_name: @token_name, cost: @cost }.freeze
       end
@@ -84,20 +86,49 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Integer | Array[Hash[Symbol, RepairEdit::document_value]]]
       def to_h
         { cost: @cost, configurations: @configurations, edits: @edits.map(&:to_h).freeze }.freeze
       end
     end
 
+    # Closed internal outcome for callers that must distinguish bounded search
+    # exhaustion from a complete search with no repair.
+    class RepairSearchResult
+      STATUSES = %i[selected need_input exhausted not_found].freeze #: Array[Symbol]
+
+      attr_reader :status #: Symbol
+      attr_reader :plan #: RepairPlan?
+      attr_reader :configurations #: Integer
+
+      # @rbs (status: Symbol, plan: RepairPlan?, configurations: Integer) -> void
+      def initialize(status:, plan:, configurations:)
+        raise ArgumentError, "unknown repair search status #{status.inspect}" unless STATUSES.include?(status)
+        unless configurations.is_a?(Integer) && configurations >= 0
+          raise ArgumentError, "repair search configurations must be nonnegative"
+        end
+        unless (status == :selected) == plan.is_a?(RepairPlan)
+          raise ArgumentError, "selected repair search status and plan must agree"
+        end
+
+        @status = status
+        @plan = plan
+        @configurations = configurations
+        freeze
+      end
+
+      # @rbs () -> bool
+      def selected? = @status == :selected
+    end
+
     # Internal normalized input record retained while repair looks ahead.
     class RepairInput
       attr_reader :token_id #: Integer
       attr_reader :token_name #: String
-      attr_reader :value #: untyped
-      attr_reader :location #: untyped
+      attr_reader :value #: Object?
+      attr_reader :location #: Object?
 
-      # @rbs (token_id: Integer, token_name: String, value: untyped, location: untyped) -> void
+      # @rbs (token_id: Integer, token_name: String, value: Object?, location: Object?) -> void
       def initialize(token_id:, token_name:, value:, location:)
         @token_id = token_id
         @token_name = token_name.dup.freeze

data/lib/ibex/runtime/repair_priority_queue.rb

@@ -5,7 +5,9 @@ module Ibex
   module Runtime
     # Minimal binary heap ordered by an immutable Array priority.
     class RepairPriorityQueue
-      # @rbs @entries: Array[[Array[untyped], untyped]]
+      # @rbs!
+      #   type priority = Array[untyped]
+      # @rbs @entries: Array[[priority, Object?]]
 
       # @rbs () -> void
       def initialize
@@ -15,9 +17,9 @@ module Ibex
       # @rbs () -> bool
       def empty? = @entries.empty?
 
-      # @rbs (Array[untyped] priority, untyped value) -> void
+      # @rbs (priority priority, Object? value) -> void
       def push(priority, value)
-        entry = [priority, value] #: [Array[untyped], untyped]
+        entry = [priority, value] #: [priority, Object?]
         @entries << entry
         index = @entries.length - 1
         while index.positive?
@@ -30,7 +32,7 @@ module Ibex
         @entries[index] = entry
       end
 
-      # @rbs () -> [Array[untyped], untyped]?
+      # @rbs () -> [priority, Object?]?
       def pop
         first = @entries.first
         tail = @entries.pop
@@ -51,9 +53,11 @@ module Ibex
 
       private
 
-      # @rbs ([Array[untyped], untyped] left, [Array[untyped], untyped] right) -> Integer
+      # @rbs ([priority, Object?] left, [priority, Object?] right) -> Integer
       def compare(left, right)
-        (left.fetch(0) <=> right.fetch(0)) || 0
+        left_priority = left.fetch(0) #: priority
+        right_priority = right.fetch(0) #: priority
+        (left_priority <=> right_priority) || 0
       end
     end
   end

data/lib/ibex/runtime/repair_search.rb

@@ -8,20 +8,34 @@ module Ibex
     # Bounded Dijkstra search over LR state stacks. Semantic actions never run.
     # rubocop:disable Metrics/ClassLength -- queue policy and LR transitions form one bounded search invariant.
     class RepairSearch
+      # @rbs!
+      #   type configuration_key = [Array[Integer], Integer, Integer, bool]
+      #   type priority = Array[untyped]
+      #   type lookup_table = Tables::action_table | Tables::goto_table
+      #   type lookup_value = IR::runtime_action | Integer?
+
       NEED_INPUT = Object.new.freeze #: Object
       LIMIT = Object.new.freeze #: Object
-      Configuration = Struct.new(:stack, :input_index, :shifts, :cost, :edits, :goal, keyword_init: true)
-
-      # @rbs @tables: Hash[Symbol, untyped]
+      Configuration = Struct.new(
+        :stack, #: Array[Integer]
+        :input_index, #: Integer
+        :shifts, #: Integer
+        :cost, #: Integer
+        :edits, #: Array[RepairEdit]
+        :goal, #: bool
+        keyword_init: true
+      )
+
+      # @rbs @tables: Hash[Symbol, Object?]
       # @rbs @policy: RepairPolicy
       # @rbs @tokens: Array[RepairInput]
       # @rbs @complete: bool
       # @rbs @configurations: Integer
       # @rbs @heap: RepairPriorityQueue
-      # @rbs @best: Hash[Array[untyped], Array[untyped]]
+      # @rbs @best: Hash[configuration_key, priority]
       # @rbs @candidate_ids: Array[Integer]
 
-      # @rbs (Hash[Symbol, untyped] tables, RepairPolicy policy, Array[RepairInput] tokens,
+      # @rbs (Hash[Symbol, Object?] tables, RepairPolicy policy, Array[RepairInput] tokens,
       #   complete: bool) -> void
       def initialize(tables, policy, tokens, complete:)
         @tables = tables
@@ -32,11 +46,23 @@ module Ibex
         @heap = RepairPriorityQueue.new
         @best = {}
         reserved = [Parser::EOF_TOKEN, Parser::ERROR_TOKEN]
-        @candidate_ids = tables.fetch(:token_names).keys.reject { |id| reserved.include?(id) }.sort.freeze
+        token_names = tables.fetch(:token_names) #: Hash[Integer, String]
+        @candidate_ids = token_names.keys.reject { |id| reserved.include?(id) }.sort.freeze
       end
 
+      # Compatibility projection used by the semantic runtime path.
       # @rbs (Array[Integer] state_stack) -> (RepairPlan | Object | nil)
       def search(state_stack)
+        result = search_result(state_stack)
+        return result.plan if result.selected?
+        return NEED_INPUT if result.status == :need_input
+
+        nil
+      end
+
+      # Preserve the bounded outcome for syntax tooling and diagnostics.
+      # @rbs (Array[Integer] state_stack) -> RepairSearchResult
+      def search_result(state_stack)
         empty_edits = [] #: Array[RepairEdit]
         push(
           Configuration.new(
@@ -51,16 +77,16 @@ module Ibex
         needs_input = false
         until @heap.empty?
           configuration = pop
-          return nil if configuration.equal?(LIMIT)
+          return outcome(:exhausted) if configuration.equal?(LIMIT)
           next unless configuration.is_a?(Configuration)
 
           result = visit(configuration)
-          return nil if result.equal?(LIMIT)
-          return result if result.is_a?(RepairPlan)
+          return outcome(:exhausted) if result.equal?(LIMIT)
+          return outcome(:selected, plan: result) if result.is_a?(RepairPlan)
 
           needs_input = true if result.equal?(NEED_INPUT)
         end
-        needs_input ? NEED_INPUT : nil
+        outcome(needs_input ? :need_input : :not_found)
       end
 
       private
@@ -206,11 +232,18 @@ module Ibex
           action = action_for(states.last, token_id)
           case action.first
           when :shift
-            states << action.fetch(1)
+            target = action.fetch(1)
+            return nil unless target.is_a?(Integer)
+
+            states << target
             return nil if states.length > @policy.max_stack
 
             return RepairAdvance.new(status: :shift, stack: states.freeze)
-          when :reduce then return nil unless apply_reduction(states, action.fetch(1))
+          when :reduce
+            production_id = action.fetch(1)
+            return nil unless production_id.is_a?(Integer)
+
+            return nil unless apply_reduction(states, production_id)
           when :accept then return RepairAdvance.new(status: :accept, stack: states.freeze)
           else return nil
           end
@@ -219,31 +252,53 @@ module Ibex
 
       # @rbs (Array[Integer] states, Integer production_id) -> Array[Integer]?
       def apply_reduction(states, production_id)
-        production = @tables.fetch(:productions).fetch(production_id)
-        length = production.fetch(:length)
+        productions = @tables.fetch(:productions) #: Array[Hash[Symbol, Object?]]
+        production = productions.fetch(production_id)
+        length = production.fetch(:length) #: Integer
         return if length >= states.length
 
         states.pop(length)
-        goto = table_lookup(@tables.fetch(:gotos), states.last, production.fetch(:lhs))
-        return unless goto
+        gotos = @tables.fetch(:gotos) #: Tables::goto_table
+        lhs = production.fetch(:lhs) #: Integer
+        goto = goto_table_lookup(gotos, states.last, lhs)
+        return unless goto.is_a?(Integer)
 
         states << goto
         states if states.length <= @policy.max_stack
       end
 
-      # @rbs (Integer state, Integer token_id) -> untyped
+      # @rbs (Integer state, Integer token_id) -> IR::runtime_action
       def action_for(state, token_id)
-        explicit = table_lookup(@tables.fetch(:actions), state, token_id)
+        actions = @tables.fetch(:actions) #: Tables::action_table
+        explicit = action_table_lookup(actions, state, token_id)
         return explicit if explicit
 
-        @tables.fetch(:default_actions, Parser::EMPTY_ROW)[state] || [:error]
+        defaults = @tables.fetch(:default_actions, Parser::EMPTY_ROW) #: Array[IR::runtime_action?]
+        defaults[state] || [:error]
       end
 
-      # @rbs (untyped table, Integer row, Integer column) -> untyped
-      def table_lookup(table, row, column)
-        return table.lookup(row, column) if table.respond_to?(:lookup)
+      # @rbs (Tables::action_table table, Integer row, Integer column) -> IR::runtime_action?
+      def action_table_lookup(table, row, column)
+        if table.is_a?(Tables::CompactActions)
+          value = table.__send__(:lookup, row, column)
+          return value #: IR::runtime_action?
+        end
 
-        table.fetch(row, Parser::EMPTY_ROW)[column]
+        rows = table #: Array[Hash[Integer, IR::runtime_action]]
+        empty_row = Parser::EMPTY_ROW #: Hash[Integer, IR::runtime_action]
+        rows.fetch(row, empty_row)[column]
+      end
+
+      # @rbs (Tables::goto_table table, Integer row, Integer column) -> Integer?
+      def goto_table_lookup(table, row, column)
+        if table.is_a?(Tables::Compact)
+          value = table.__send__(:lookup, row, column)
+          return value #: Integer?
+        end
+
+        rows = table #: Array[Hash[Integer, Integer]]
+        empty_row = Parser::EMPTY_ROW #: Hash[Integer, Integer]
+        rows.fetch(row, empty_row)[column]
       end
 
       # @rbs (Configuration source, ?stack: Array[Integer], ?input_index: Integer, ?shifts: Integer,
@@ -260,15 +315,22 @@ module Ibex
         RepairPlan.new(edits: edits, configurations: @configurations)
       end
 
+      # @rbs (Symbol status, ?plan: RepairPlan?) -> RepairSearchResult
+      def outcome(status, plan: nil)
+        RepairSearchResult.new(status: status, plan: plan, configurations: @configurations)
+      end
+
       # @rbs (Integer token_id) -> String
       def token_name(token_id)
-        @tables.fetch(:token_names).fetch(token_id, token_id.to_s)
+        token_names = @tables.fetch(:token_names) #: Hash[Integer, String]
+        token_names.fetch(token_id, token_id.to_s)
       end
 
       # @rbs (Configuration configuration) -> void
       def push(configuration)
         priority = priority_for(configuration)
-        key = [configuration.stack, configuration.input_index, configuration.shifts, configuration.goal]
+        key = [configuration.stack, configuration.input_index, configuration.shifts,
+               configuration.goal] #: configuration_key
         previous = @best[key]
         comparison = previous <=> priority if previous
         return if comparison && comparison <= 0
@@ -286,23 +348,24 @@ module Ibex
           priority, configuration = entry
           return LIMIT unless configuration.is_a?(Configuration)
 
-          key = [configuration.stack, configuration.input_index, configuration.shifts, configuration.goal]
+          key = [configuration.stack, configuration.input_index, configuration.shifts,
+                 configuration.goal] #: configuration_key
           return configuration if @best[key] == priority
         end
       end
 
-      # @rbs (Configuration configuration) -> Array[untyped]
+      # @rbs (Configuration configuration) -> priority
       def priority_for(configuration)
         edit_key = configuration.edits.map do |edit|
           rank = { delete: 0, insert: 1, replace: 2 }.fetch(edit.kind)
-          [edit.position, rank, edit.token_id]
+          [edit.position, rank, edit.token_id] #: [Integer, Integer, Integer]
         end
         goal_rank = configuration.goal ? 0 : 1
         risk = configuration.edits.sum { |edit| semantic_value_risk(edit) }
         [
           configuration.cost, risk, edit_key, goal_rank, -configuration.shifts,
           configuration.input_index, configuration.stack
-        ]
+        ] #: priority
       end
 
       # Prefer punctuation edits when equal-cost repairs are otherwise