ibex 0.2.0 → 0.4.0

data/lib/ibex/coverage/event_stream.rb

@@ -10,6 +10,9 @@ module Ibex
   module Coverage
     # Bounded reader for the public runtime-event JSON Lines protocol.
     module EventStream
+      # @rbs!
+      #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
       # @rbs!
       #   interface _CoverageEventInput
       #     def gets: (Integer) -> String?
@@ -21,13 +24,13 @@ module Ibex
       EVENT_TYPES = %w[start shift reduce error recover discard accept reject].freeze #: Array[String]
 
       class << self
-        # @rbs (String path) { (Hash[String, untyped], Integer) -> void } -> void
+        # @rbs (String path) { (Hash[String, json_value], Integer) -> void } -> void
         def each_file(path, &block)
           File.open(path, "rb") { |input| each_io(input, source: path, &block) }
         end
 
         # @rbs (_CoverageEventInput input, source: String)
-        #   { (Hash[String, untyped], Integer) -> void } -> void
+        #   { (Hash[String, json_value], Integer) -> void } -> void
         def each_io(input, source:, &block)
           line_number = 0
           while (line = input.gets(MAX_LINE_BYTES + 1))
@@ -49,20 +52,23 @@ module Ibex
           raise_invalid(source, line_number, "event line exceeds #{MAX_LINE_BYTES} bytes")
         end
 
-        # @rbs (String line, String source, Integer line_number) -> Hash[String, untyped]
+        # @rbs (String line, String source, Integer line_number) -> Hash[String, json_value]
         def parse_line(line, source, line_number)
           text = line.dup.force_encoding(Encoding::UTF_8)
           raise_invalid(source, line_number, "event line is not valid UTF-8") unless text.valid_encoding?
 
-          value = JSON.parse(text, max_nesting: MAX_NESTING, allow_nan: false)
-          return value if value.is_a?(Hash) && value.keys.all?(String)
+          value = JSON.parse(text, max_nesting: MAX_NESTING, allow_nan: false) #: json_value
+          if value.is_a?(Hash) && value.keys.all?(String)
+            document = value #: Hash[String, json_value]
+            return document
+          end
 
           raise_invalid(source, line_number, "event line must be a JSON object")
         rescue JSON::ParserError => e
           raise_invalid(source, line_number, "invalid event JSON: #{e.message}")
         end
 
-        # @rbs (Hash[String, untyped] document, String source, Integer line_number) -> void
+        # @rbs (Hash[String, json_value] document, String source, Integer line_number) -> void
         def validate_envelope(document, source, line_number)
           unless document.keys.sort == ROOT_KEYS
             raise_invalid(source, line_number, "event object has unknown or missing fields")
@@ -82,7 +88,7 @@ module Ibex
           raise_invalid(source, line_number, "event data does not match the runtime-event v1 schema")
         end
 
-        # @rbs (untyped value) -> bool
+        # @rbs (json_value value) -> bool
         def positive_integer?(value)
           value.is_a?(Integer) && value.positive?
         end

data/lib/ibex/coverage/report.rb

@@ -8,6 +8,9 @@ module Ibex
   module Coverage
     # Versioned, mergeable runtime coverage result.
     class Report
+      # @rbs!
+      #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
       IDENTIFIER = "runtime-coverage" #: String
       SCHEMA_VERSION = 1 #: Integer
       MAX_DOCUMENT_BYTES = 16_777_216 #: Integer
@@ -46,7 +49,7 @@ module Ibex
       end
       # rubocop:enable Layout/LineLength
 
-      # @rbs () -> Hash[String, untyped]
+      # @rbs () -> Hash[String, json_value]
       def to_h
         {
           "ibex_coverage" => IDENTIFIER,
@@ -61,7 +64,7 @@ module Ibex
         }
       end
 
-      # @rbs (*untyped) -> String
+      # @rbs (*Object) -> String
       def to_json(*)
         "#{JSON.pretty_generate(to_h)}\n"
       end
@@ -87,7 +90,7 @@ module Ibex
         raise Ibex::Error, "#{path}:1:1: invalid coverage JSON: #{e.message}"
       end
 
-      # @rbs (untyped value, source: String) -> Report
+      # @rbs (json_value value, source: String) -> Report
       def self.from_h(value, source:)
         document = string_hash(value, source, "coverage document")
         invalid(source, "coverage object has unknown or missing fields") unless document.keys.sort == ROOT_KEYS
@@ -97,15 +100,19 @@ module Ibex
         totals = string_hash(document["totals"], source, "coverage totals")
         invalid(source, "coverage totals have unknown or missing fields") unless totals.keys.sort == TOTAL_KEYS
 
-        state_count = totals["states"]
-        production_count = totals["productions"]
+        grammar_digest = document["grammar_digest"] #: String
+        table_format_version = document["table_format_version"] #: Integer
+        state_count = totals["states"] #: Integer
+        production_count = totals["productions"] #: Integer
+        sessions = document["sessions"] #: Integer
+        event_count = document["events"] #: Integer
         new(
-          grammar_digest: document["grammar_digest"],
-          table_format_version: document["table_format_version"],
+          grammar_digest: grammar_digest,
+          table_format_version: table_format_version,
           state_count: state_count,
           production_count: production_count,
-          sessions: document["sessions"],
-          event_count: document["events"],
+          sessions: sessions,
+          event_count: event_count,
           state_hits: parse_hits(document["state_hits"], state_count, source, "state"),
           production_hits: parse_hits(document["production_hits"], production_count, source, "production")
         )
@@ -133,22 +140,21 @@ module Ibex
 
       private
 
-      # @rbs (untyped input) -> String
+      # @rbs (json_value input) -> String
       def validate_digest(input)
-        valid = input.is_a?(String) && input.match?(/\Asha256:[0-9a-f]{64}\z/)
-        return input.dup.freeze if valid
+        return input.dup.freeze if input.is_a?(String) && input.match?(/\Asha256:[0-9a-f]{64}\z/)
 
         raise ArgumentError, "grammar_digest must be a full lowercase SHA-256 digest"
       end
 
-      # @rbs (untyped input, String name) -> Integer
+      # @rbs (json_value input, String name) -> Integer
       def positive_integer(input, name)
         return input if input.is_a?(Integer) && input.positive? && input <= MAX_COUNT
 
         raise ArgumentError, "#{name} must be a bounded positive integer"
       end
 
-      # @rbs (untyped input, String name, minimum: Integer) -> Integer
+      # @rbs (json_value input, String name, minimum: Integer) -> Integer
       def total_integer(input, name, minimum:)
         return input if input.is_a?(Integer) && input >= minimum && input <= MAX_TOTAL
 
@@ -182,14 +188,16 @@ module Ibex
       class << self
         private
 
-        # @rbs (untyped value, String source, String name) -> Hash[String, untyped]
+        # @rbs (json_value value, String source, String name) -> Hash[String, json_value]
         def string_hash(value, source, name)
-          return value if value.is_a?(Hash) && value.keys.all?(String)
+          if value.is_a?(Hash) && value.keys.all?(String)
+            return value #: Hash[String, json_value]
+          end
 
           invalid(source, "#{name} must be an object")
         end
 
-        # @rbs (untyped value, untyped total, String source, String kind) -> Hash[Integer, Integer]
+        # @rbs (json_value value, json_value total, String source, String kind) -> Hash[Integer, Integer]
         def parse_hits(value, total, source, kind)
           invalid(source, "#{kind}_hits must be an array") unless value.is_a?(Array)
           hits = {} #: Hash[Integer, Integer]
@@ -202,7 +210,7 @@ module Ibex
           hits
         end
 
-        # @rbs (untyped entry, untyped total, Integer previous, String source, String kind) -> [Integer, Integer]
+        # @rbs (json_value entry, json_value total, Integer previous, String source, String kind) -> [Integer, Integer]
         def parse_hit(entry, total, previous, source, kind)
           hit = string_hash(entry, source, "#{kind} hit")
           invalid(source, "#{kind} hit has unknown or missing fields") unless hit.keys.sort == HIT_KEYS

data/lib/ibex/coverage/runtime_event_validator.rb

@@ -5,6 +5,9 @@ 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 = {
@@ -19,18 +22,23 @@ module Ibex
       }.freeze #: Hash[String, Symbol]
 
       class << self
-        # @rbs (Hash[String, untyped] document) -> bool
+        # @rbs (Hash[String, json_value] document) -> bool
         def valid?(document)
           data = document["data"]
           return false unless data.is_a?(Hash) && data.keys.all?(String)
 
-          validator = VALIDATORS[document["event"]]
-          validator ? send(validator, data) : false
+          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, untyped] data) -> bool
+        # @rbs (Hash[String, json_value] data) -> bool
         def valid_start?(data)
           return false unless exact_keys?(
             data,
@@ -45,45 +53,46 @@ module Ibex
             optional_string?(data["grammar_digest"])
         end
 
-        # @rbs (Hash[String, untyped] data) -> bool
+        # @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, untyped] data) -> bool
+        # @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]) } &&
-            integer?(data["rhs_length"]) && data["rhs_length"] >= 0 &&
+            rhs_length.is_a?(Integer) && rhs_length >= 0 &&
             summary?(data["result"]) && location?(data["location"])
         end
 
-        # @rbs (Hash[String, untyped] data, reasons: Array[String]) -> bool
+        # @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, untyped] data) -> bool
+        # @rbs (Hash[String, json_value] data) -> bool
         def valid_error?(data)
           valid_token_event?(data, reasons: %w[syntax semantic])
         end
 
-        # @rbs (Hash[String, untyped] data) -> bool
+        # @rbs (Hash[String, json_value] data) -> bool
         def valid_discard?(data)
           valid_token_event?(data, reasons: %w[recovery])
         end
 
-        # @rbs (Hash[String, untyped] data) -> bool
+        # @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, untyped] data) -> bool
+        # @rbs (Hash[String, json_value] data) -> bool
         def valid_recover?(data)
           exact_keys?(data, TOKEN_KEYS + %w[from_state reason]) &&
             valid_token_fields?(data) &&
@@ -91,7 +100,7 @@ module Ibex
             %w[syntax semantic].include?(data["reason"])
         end
 
-        # @rbs (Hash[String, untyped] data) -> bool
+        # @rbs (Hash[String, json_value] data) -> bool
         def valid_accept?(data)
           exact_keys?(data, %w[reason result state]) &&
             integer?(data["state"]) &&
@@ -99,7 +108,7 @@ module Ibex
             %w[table semantic].include?(data["reason"])
         end
 
-        # @rbs (Hash[String, untyped] data) -> bool
+        # @rbs (Hash[String, json_value] data) -> bool
         def valid_token_fields?(data)
           integer?(data["state"]) &&
             optional_integer?(data["token_id"]) &&
@@ -108,7 +117,7 @@ module Ibex
             location?(data["location"])
         end
 
-        # @rbs (untyped value) -> bool
+        # @rbs (json_value value) -> bool
         def summary?(value)
           case value
           when nil, true, false, Integer then true
@@ -118,7 +127,7 @@ module Ibex
           end
         end
 
-        # @rbs (untyped value) -> bool
+        # @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)
@@ -126,7 +135,7 @@ module Ibex
           value.keys.all?(String) && value.length <= 17 && value.values.all? { |entry| summary?(entry) }
         end
 
-        # @rbs (untyped value) -> bool
+        # @rbs (json_value value) -> bool
         def location?(value)
           return true if value.nil?
           return false unless value.is_a?(Hash) && value.keys.all?(String)
@@ -135,22 +144,22 @@ module Ibex
           (value.keys - LOCATION_KEYS).empty? && value.values.all? { |entry| summary?(entry) }
         end
 
-        # @rbs (Hash[String, untyped] data, Array[String] keys) -> bool
+        # @rbs (Hash[String, json_value] data, Array[String] keys) -> bool
         def exact_keys?(data, keys)
           data.keys.sort == keys.sort
         end
 
-        # @rbs (untyped value) -> bool
+        # @rbs (json_value value) -> bool
         def integer?(value)
           value.is_a?(Integer)
         end
 
-        # @rbs (untyped value) -> bool
+        # @rbs (json_value value) -> bool
         def optional_integer?(value)
           value.nil? || integer?(value)
         end
 
-        # @rbs (untyped value) -> bool
+        # @rbs (json_value value) -> bool
         def optional_string?(value)
           value.nil? || value.is_a?(String)
         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,141 @@
+# 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,
+            documentation: symbol.documentation
+          }
+        ]
+      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