ibex 0.1.0 → 0.3.0

data/lib/ibex/coverage/runtime_event_validator.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Coverage
+    # Dependency-free structural validation for runtime-event schema version 1.
+    module RuntimeEventValidator
+      # @rbs!
+      #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
+      TOKEN_KEYS = %w[location state token token_id value].freeze #: Array[String]
+      LOCATION_KEYS = %w[column end_column end_line file line].freeze #: Array[String]
+      VALIDATORS = {
+        "start" => :valid_start?,
+        "shift" => :valid_shift?,
+        "reduce" => :valid_reduce?,
+        "error" => :valid_error?,
+        "recover" => :valid_recover?,
+        "discard" => :valid_discard?,
+        "accept" => :valid_accept?,
+        "reject" => :valid_reject?
+      }.freeze #: Hash[String, Symbol]
+
+      class << self
+        # @rbs (Hash[String, json_value] document) -> bool
+        def valid?(document)
+          data = document["data"]
+          return false unless data.is_a?(Hash) && data.keys.all?(String)
+
+          event_data = data #: Hash[String, json_value]
+
+          event = document["event"]
+          return false unless event.is_a?(String)
+
+          validator = VALIDATORS[event]
+          validator ? send(validator, event_data) : false
+        end
+
+        private
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_start?(data)
+          return false unless exact_keys?(
+            data,
+            %w[driver grammar_digest initial_state production_count state_count table_format_version]
+          )
+
+          integer_fields = %w[initial_state table_format_version]
+          optional_integer_fields = %w[state_count production_count]
+          %w[pull push].include?(data["driver"]) &&
+            integer_fields.all? { |key| integer?(data[key]) } &&
+            optional_integer_fields.all? { |key| optional_integer?(data[key]) } &&
+            optional_string?(data["grammar_digest"])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_shift?(data)
+          exact_keys?(data, TOKEN_KEYS + %w[from_state]) &&
+            valid_token_fields?(data) &&
+            integer?(data["from_state"])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_reduce?(data)
+          keys = %w[goto_state lhs location post_state pre_state production_id result rhs_length]
+          rhs_length = data["rhs_length"]
+          exact_keys?(data, keys) &&
+            %w[goto_state lhs post_state pre_state production_id].all? { |key| integer?(data[key]) } &&
+            rhs_length.is_a?(Integer) && rhs_length >= 0 &&
+            summary?(data["result"]) && location?(data["location"])
+        end
+
+        # @rbs (Hash[String, json_value] data, reasons: Array[String]) -> bool
+        def valid_token_event?(data, reasons:)
+          exact_keys?(data, TOKEN_KEYS + %w[reason]) &&
+            valid_token_fields?(data) &&
+            reasons.include?(data["reason"])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_error?(data)
+          valid_token_event?(data, reasons: %w[syntax semantic])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_discard?(data)
+          valid_token_event?(data, reasons: %w[recovery])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_reject?(data)
+          valid_token_event?(data, reasons: %w[eof_during_recovery no_recovery_state])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_recover?(data)
+          exact_keys?(data, TOKEN_KEYS + %w[from_state reason]) &&
+            valid_token_fields?(data) &&
+            integer?(data["from_state"]) &&
+            %w[syntax semantic].include?(data["reason"])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_accept?(data)
+          exact_keys?(data, %w[reason result state]) &&
+            integer?(data["state"]) &&
+            summary?(data["result"]) &&
+            %w[table semantic].include?(data["reason"])
+        end
+
+        # @rbs (Hash[String, json_value] data) -> bool
+        def valid_token_fields?(data)
+          integer?(data["state"]) &&
+            optional_integer?(data["token_id"]) &&
+            summary?(data["token"]) &&
+            summary?(data["value"]) &&
+            location?(data["location"])
+        end
+
+        # @rbs (json_value value) -> bool
+        def summary?(value)
+          case value
+          when nil, true, false, Integer then true
+          when Float then value.finite?
+          when String then value.length <= 256
+          else composite_summary?(value)
+          end
+        end
+
+        # @rbs (json_value value) -> bool
+        def composite_summary?(value)
+          return value.length <= 17 && value.all? { |entry| summary?(entry) } if value.is_a?(Array)
+          return false unless value.is_a?(Hash)
+
+          value.keys.all?(String) && value.length <= 17 && value.values.all? { |entry| summary?(entry) }
+        end
+
+        # @rbs (json_value value) -> bool
+        def location?(value)
+          return true if value.nil?
+          return false unless value.is_a?(Hash) && value.keys.all?(String)
+          return value["unavailable"].is_a?(String) if value.keys == ["unavailable"]
+
+          (value.keys - LOCATION_KEYS).empty? && value.values.all? { |entry| summary?(entry) }
+        end
+
+        # @rbs (Hash[String, json_value] data, Array[String] keys) -> bool
+        def exact_keys?(data, keys)
+          data.keys.sort == keys.sort
+        end
+
+        # @rbs (json_value value) -> bool
+        def integer?(value)
+          value.is_a?(Integer)
+        end
+
+        # @rbs (json_value value) -> bool
+        def optional_integer?(value)
+          value.nil? || integer?(value)
+        end
+
+        # @rbs (json_value value) -> bool
+        def optional_string?(value)
+          value.nil? || value.is_a?(String)
+        end
+      end
+    end
+  end
+end

data/lib/ibex/coverage.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "coverage/runtime_event_validator"
+require_relative "coverage/event_stream"
+require_relative "coverage/report"
+require_relative "coverage/collector"
+
+module Ibex
+  # Deterministic state and production coverage derived from runtime event streams.
+  module Coverage
+  end
+end

data/lib/ibex/delta_reducer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  # Deterministic, trial-bounded delta debugging over an ordered sequence.
+  class DeltaReducer
+    # Immutable outcome of a bounded reduction.
+    class Result
+      attr_reader :items #: Array[untyped]
+      attr_reader :trials #: Integer
+      attr_reader :complete #: bool
+      attr_reader :original_size #: Integer
+
+      # @rbs (items: Array[untyped], trials: Integer, complete: bool, original_size: Integer) -> void
+      def initialize(items:, trials:, complete:, original_size:)
+        @items = items.freeze
+        @trials = trials
+        @complete = complete
+        @original_size = original_size
+        freeze
+      end
+    end
+
+    # @rbs (?max_trials: Integer) -> void
+    def initialize(max_trials: 1_000)
+      raise ArgumentError, "max_trials must be positive" unless max_trials.positive?
+
+      @max_trials = max_trials
+    end
+
+    # `failure` must return true while the failure of interest is preserved.
+    # @rbs [T] (Array[T] items) { (Array[T]) -> bool } -> Result
+    def minimize(items, &failure)
+      raise ArgumentError, "a failure predicate is required" unless failure
+
+      current = items.dup
+      original_size = current.length
+      trials = 0
+      trials = checked_trial!(trials)
+      unless failure.call(current.freeze)
+        raise Ibex::Error, "(reduce):1:1: original input does not reproduce the failure"
+      end
+
+      granularity = 2
+      while current.length >= 1
+        chunks = partitions(current.length, granularity)
+        reduced = false
+        chunks.each do |range|
+          return result(current, trials, false, original_size) if trials >= @max_trials
+
+          candidate = current.dup
+          candidate.slice!(range)
+          trials = checked_trial!(trials)
+          next unless failure.call(candidate.freeze)
+
+          current = candidate
+          granularity = [granularity - 1, 2].max
+          reduced = true
+          break
+        end
+        next if reduced
+        break if granularity >= current.length
+
+        granularity = [granularity * 2, current.length].min
+      end
+
+      result(current, trials, true, original_size)
+    end
+
+    private
+
+    # @rbs (Integer length, Integer count) -> Array[Range[Integer]]
+    def partitions(length, count)
+      width = (length.to_f / count).ceil
+      ranges = [] #: Array[Range[Integer]]
+      count.times do |index|
+        start = index * width
+        break if start >= length
+
+        ranges << (start...[start + width, length].min)
+      end
+      ranges
+    end
+
+    # @rbs (Integer trials) -> Integer
+    def checked_trial!(trials)
+      raise Ibex::Error, "(reduce):1:1: trial limit of #{@max_trials} is exhausted" if trials >= @max_trials
+
+      trials + 1
+    end
+
+    # @rbs (Array[untyped] items, Integer trials, bool complete, Integer original_size) -> Result
+    def result(items, trials, complete, original_size)
+      Result.new(
+        items: items.dup.freeze, trials: trials, complete: complete, original_size: original_size
+      ).freeze
+    end
+  end
+end

data/lib/ibex/diff.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  # Deterministic grammar and automaton change classification.
+  class Diff
+    # @rbs (IR::Automaton before, IR::Automaton after) -> void
+    def initialize(before, after)
+      @before = before
+      @after = after
+    end
+
+    # @rbs () -> Hash[Symbol, Object?]
+    def to_h
+      {
+        ibex_report: "diff", schema_version: 1,
+        symbols: classify(symbol_records(@before.grammar), symbol_records(@after.grammar)),
+        rules: classify(rule_records(@before.grammar), rule_records(@after.grammar)),
+        conflicts: classify(conflict_records(@before), conflict_records(@after)),
+        warnings: classify(warning_records(@before.grammar), warning_records(@after.grammar)),
+        metrics: numeric_metrics
+      }
+    end
+
+    private
+
+    # @rbs (Hash[String, Object?] before, Hash[String, Object?] after) -> Hash[Symbol, Object?]
+    def classify(before, after)
+      common = before.keys & after.keys
+      {
+        added: (after.keys - before.keys).sort.map { |key| { id: key, value: after.fetch(key) } },
+        removed: (before.keys - after.keys).sort.map { |key| { id: key, value: before.fetch(key) } },
+        changed: common.sort.filter_map do |key|
+          next if before.fetch(key) == after.fetch(key)
+
+          { id: key, before: before.fetch(key), after: after.fetch(key) }
+        end
+      }
+    end
+
+    # @rbs (IR::Grammar grammar) -> Hash[String, Object?]
+    def symbol_records(grammar)
+      grammar.symbols.to_h do |symbol|
+        [
+          symbol.name,
+          {
+            kind: symbol.kind, reserved: symbol.reserved, display_name: symbol.display_name,
+            semantic_type: symbol.semantic_type, precedence: symbol.precedence
+          }
+        ]
+      end
+    end
+
+    # @rbs (IR::Grammar grammar) -> Hash[String, Object?]
+    def rule_records(grammar)
+      grammar.productions.group_by(&:lhs).to_h do |lhs, productions|
+        name = grammar.symbol_by_id(lhs)&.name || lhs.to_s
+        alternatives = productions.map { |production| production_record(grammar, production) }
+        [name, alternatives]
+      end
+    end
+
+    # @rbs (IR::Grammar grammar, IR::Production production) -> Hash[Symbol, Object?]
+    def production_record(grammar, production)
+      precedence = production.precedence_override
+      {
+        rhs: production.rhs.map { |id| symbol_name(grammar, id) },
+        precedence: precedence && symbol_name(grammar, precedence),
+        node: production.node && {
+          name: production.node.fetch(:name), fields: production.node.fetch(:fields)
+        }
+      }
+    end
+
+    # @rbs (IR::Automaton automaton) -> Hash[String, Object?]
+    def conflict_records(automaton)
+      grouped = Hash.new { |hash, key| hash[key] = [] } #: Hash[String, Array[Object?]]
+      automaton.states.each do |state|
+        state.conflicts.each do |conflict|
+          identity = conflict_identity(automaton.grammar, conflict)
+          grouped[identity] << conflict.fetch(:resolution)
+        end
+      end
+      grouped.transform_values { |resolutions| resolutions.sort_by(&:inspect) }
+    end
+
+    # @rbs (IR::Grammar grammar, IR::conflict conflict) -> String
+    def conflict_identity(grammar, conflict)
+      if conflict.fetch(:type).to_sym == :shift_reduce
+        shift_reduce = conflict #: IR::shift_reduce_conflict
+        reduction = production_shape(grammar, shift_reduce.fetch(:reduce))
+        "shift_reduce:#{shift_reduce.fetch(:symbol)}:#{reduction}"
+      else
+        reduce_reduce = conflict #: IR::reduce_reduce_conflict
+        reductions = reduce_reduce.fetch(:reductions).map { |id| production_shape(grammar, id) }.sort
+        "reduce_reduce:#{reduce_reduce.fetch(:symbol)}:#{reductions.join('|')}"
+      end
+    end
+
+    # @rbs (IR::Grammar grammar, Integer id) -> String
+    def production_shape(grammar, id)
+      production = grammar.productions.fetch(id)
+      lhs = symbol_name(grammar, production.lhs)
+      rhs = production.rhs.map { |symbol| symbol_name(grammar, symbol) }
+      "#{lhs}->#{rhs.join(' ')}"
+    end
+
+    # @rbs (IR::Grammar grammar, Integer id) -> String
+    def symbol_name(grammar, id)
+      grammar.symbol_by_id(id)&.name || id.to_s
+    end
+
+    # @rbs (IR::Grammar grammar) -> Hash[String, Object?]
+    def warning_records(grammar)
+      grouped = Hash.new { |hash, key| hash[key] = [] } #: Hash[String, Array[Object?]]
+      grammar.warnings.each do |warning|
+        value = warning.except(:loc)
+        identity = [warning.fetch(:type), value.except(:message).inspect].join(":")
+        grouped[identity] << value
+      end
+      grouped.transform_values { |values| values.sort_by(&:inspect) }
+    end
+
+    # @rbs () -> Hash[Symbol, Hash[Symbol, Integer]]
+    def numeric_metrics
+      {
+        states: change(@before.states.length, @after.states.length),
+        productions: change(@before.grammar.productions.length, @after.grammar.productions.length),
+        warnings: change(@before.grammar.warnings.length, @after.grammar.warnings.length),
+        shift_reduce: change(@before.conflict_summary.fetch(:sr), @after.conflict_summary.fetch(:sr)),
+        reduce_reduce: change(@before.conflict_summary.fetch(:rr), @after.conflict_summary.fetch(:rr))
+      }
+    end
+
+    # @rbs (Integer before, Integer after) -> Hash[Symbol, Integer]
+    def change(before, after)
+      { before: before, after: after, delta: after - before }
+    end
+  end
+end

data/lib/ibex/equiv/machine.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  class Equiv
+    # Immutable, semantic-action-free LR state-stack machine.
+    class Machine
+      class BudgetExceeded < Ibex::Error; end
+
+      # One product-search component.
+      class Configuration
+        attr_reader :stack #: Array[Integer]
+        attr_reader :status #: Symbol?
+        attr_reader :actions #: Integer
+        attr_reader :reductions #: Array[Integer]
+
+        # @rbs (stack: Array[Integer], status: Symbol?, actions: Integer, ?reductions: Array[Integer]) -> void
+        def initialize(stack:, status:, actions:, reductions: [])
+          @stack = stack.freeze
+          @status = status
+          @actions = actions
+          @reductions = reductions.freeze
+          freeze
+        end
+      end
+
+      # @rbs (IR::Automaton automaton, max_actions: Integer, max_stack: Integer) -> void
+      def initialize(automaton, max_actions:, max_stack:)
+        @automaton = automaton
+        @max_actions = max_actions
+        @max_stack = max_stack
+        @terminals = automaton.grammar.terminals.to_h { |symbol| [symbol.name, symbol.id] }
+        @eof_id = @terminals.fetch("$eof")
+      end
+
+      # @rbs () -> Configuration
+      def start
+        entry = @automaton.entry_states.fetch(@automaton.grammar.start)
+        Configuration.new(stack: [entry], status: nil, actions: 0, reductions: [])
+      end
+
+      # @rbs (Array[String] tokens) -> Configuration
+      def run(tokens)
+        tokens.reduce(start) { |configuration, token| push(configuration, token) }
+      end
+
+      # @rbs (Configuration configuration, String token) -> Configuration
+      def push(configuration, token)
+        return configuration if configuration.status
+
+        token_id = @terminals[token]
+        unless token_id
+          return Configuration.new(
+            stack: configuration.stack, status: :error, actions: configuration.actions,
+            reductions: configuration.reductions
+          )
+        end
+
+        consume(configuration, token_id, eof: false)
+      end
+
+      # @rbs (Configuration configuration) -> Configuration
+      def finish(configuration)
+        return configuration if configuration.status
+
+        consume(configuration, @eof_id, eof: true)
+      end
+
+      private
+
+      # @rbs (Configuration configuration, Integer token_id, eof: bool) -> Configuration
+      def consume(configuration, token_id, eof:)
+        stack = configuration.stack.dup
+        actions = configuration.actions
+        reductions = configuration.reductions.dup
+        loop do
+          actions += 1
+          enforce_action_budget!(actions)
+          state = @automaton.states.fetch(stack.fetch(-1))
+          action = state.actions.fetch(token_id, state.default_action || { type: :error })
+          case action.fetch(:type)
+          when :shift
+            shift = action #: IR::shift_action
+            stack << shift.fetch(:state)
+            enforce_stack_budget!(stack)
+            return Configuration.new(stack: stack, status: nil, actions: actions, reductions: reductions) unless eof
+          when :reduce
+            reduce = action #: IR::reduce_action
+            production_id = reduce.fetch(:production)
+            apply_reduction!(stack, production_id)
+            reductions << production_id
+            enforce_stack_budget!(stack)
+          when :accept
+            return Configuration.new(
+              stack: stack, status: :accepted, actions: actions, reductions: reductions
+            )
+          when :error
+            return Configuration.new(stack: stack, status: :error, actions: actions, reductions: reductions)
+          else
+            raise Ibex::Error, "(equiv):1:1: unknown parser action #{action.inspect}"
+          end
+        end
+      end
+
+      # @rbs (Array[Integer] stack, Integer production_id) -> void
+      def apply_reduction!(stack, production_id)
+        production = @automaton.grammar.productions.fetch(production_id)
+        if production.rhs.length >= stack.length
+          raise Ibex::Error, "(equiv):1:1: production #{production_id} underflows the state stack"
+        end
+
+        stack.pop(production.rhs.length)
+        state = @automaton.states.fetch(stack.fetch(-1))
+        target = state.gotos[production.lhs]
+        raise Ibex::Error, "(equiv):1:1: missing goto after production #{production_id}" unless target
+
+        stack << target
+      end
+
+      # @rbs (Integer actions) -> void
+      def enforce_action_budget!(actions)
+        return if actions <= @max_actions
+
+        raise BudgetExceeded, "(equiv):1:1: simulation exceeded #{@max_actions} actions"
+      end
+
+      # @rbs (Array[Integer] stack) -> void
+      def enforce_stack_budget!(stack)
+        return if stack.length <= @max_stack
+
+        raise BudgetExceeded, "(equiv):1:1: simulation exceeded stack depth #{@max_stack}"
+      end
+    end
+  end
+end