ibex 0.1.0 → 0.3.0

data/lib/ibex/equiv.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "samples"
+require_relative "verify"
+require_relative "equiv/machine"
+
+module Ibex
+  # Bounded language comparison over two immutable parser automata.
+  # rubocop:disable Metrics/ClassLength -- the three comparison strategies share one report and budget contract.
+  class Equiv
+    # @rbs!
+    #   type tree_node_signature = [String, Array[String]]
+    #   type tree_trace_entry = [String, Array[String], tree_node_signature?]
+    #   type terminal_signature = [String, [Symbol, Integer]?]
+    #   type production_signature = [String, Array[String], String?]
+
+    CAVEAT = "Bounded search is not a proof of equivalence." #: String
+    DEFAULT_MAX_ACTIONS = 100_000 #: Integer
+    DEFAULT_MAX_STACK = 10_000 #: Integer
+
+    class Difference < Ibex::Error
+      attr_reader :details #: Hash[Symbol, Object?]
+
+      # @rbs (Hash[Symbol, Object?] details) -> void
+      def initialize(details)
+        @details = IR.deep_freeze(details)
+        label = details[:witness] ? " for #{details.fetch(:witness).inspect}" : ""
+        super("(equiv):1:1: comparison found a difference#{label}")
+      end
+    end
+
+    class BudgetExceeded < Ibex::Error
+      attr_reader :details #: Hash[Symbol, Object?]
+
+      # @rbs (Hash[Symbol, Object?] details) -> void
+      def initialize(details)
+        @details = IR.deep_freeze(details)
+        super("(equiv):1:1: configured budget was exhausted")
+      end
+    end
+
+    # @rbs (IR::Automaton left, IR::Automaton right, ?sample_count: Integer, ?seed: Integer,
+    #   ?max_tokens: Integer, ?max_configurations: Integer, ?max_actions: Integer, ?max_stack: Integer,
+    #   ?rule_map: Hash[String, String]) -> void
+    def initialize(left, right, sample_count: 100, seed: 0, max_tokens: 8, max_configurations: 50_000,
+                   max_actions: DEFAULT_MAX_ACTIONS, max_stack: DEFAULT_MAX_STACK, rule_map: {})
+      budgets = {
+        sample_count: sample_count, max_tokens: max_tokens, max_configurations: max_configurations,
+        max_actions: max_actions, max_stack: max_stack
+      }
+      invalid = budgets.find { |_name, value| !value.positive? }
+      raise ArgumentError, "#{invalid.fetch(0)} must be positive" if invalid
+
+      @left = left
+      @right = right
+      @sample_count = sample_count
+      @seed = seed
+      @max_tokens = max_tokens
+      @max_configurations = max_configurations
+      @max_actions = max_actions
+      @max_stack = max_stack
+      @rule_map = rule_map.dup.freeze
+      validate_rule_map!
+      @left_machine = Machine.new(left, max_actions: max_actions, max_stack: max_stack)
+      @right_machine = Machine.new(right, max_actions: max_actions, max_stack: max_stack)
+    end
+
+    # @rbs () -> Hash[Symbol, Object?]
+    def run
+      verify_inputs!
+      structural = structural_identity?
+      tree_structural = tree_structural_identity?
+      return successful_report(structural: true, samples: 0, configurations: 0) if structural && tree_structural
+
+      samples = compare_samples
+      configurations = search_product
+      successful_report(structural: false, samples: samples, configurations: configurations)
+    rescue Machine::BudgetExceeded => e
+      raise BudgetExceeded.new(
+        result: "budget_exhausted", phase: "simulation", message: e.message,
+        bounds: bounds, statement: CAVEAT
+      )
+    rescue Ibex::Error => e
+      raise if e.is_a?(Difference) || e.is_a?(BudgetExceeded)
+      raise unless sample_budget_error?(e)
+
+      raise BudgetExceeded.new(
+        result: "budget_exhausted", phase: "sampling", message: e.message,
+        bounds: bounds, statement: CAVEAT
+      )
+    end
+
+    private
+
+    # @rbs () -> Integer
+    def compare_samples
+      left_samples = generated_samples(@left.grammar, @seed)
+      right_samples = generated_samples(@right.grammar, @seed ^ 0x1BE)
+      left_samples.each { |tokens| compare_tokens!(tokens, method: "left_to_right_sampling") }
+      right_samples.each { |tokens| compare_tokens!(tokens, method: "right_to_left_sampling") }
+      left_samples.length + right_samples.length
+    end
+
+    # @rbs (IR::Grammar grammar, Integer seed) -> Array[Array[String]]
+    def generated_samples(grammar, seed)
+      Samples.new(
+        grammar, seed: seed, max_tokens: @max_tokens, max_depth: [@max_tokens * 2, 16].max,
+                 max_expansions: [Samples::DEFAULT_MAX_EXPANSIONS, @sample_count * @max_tokens * 8].max,
+                 strategy: :coverage, path_length: 2
+      ).generate(count: @sample_count)
+    end
+
+    # @rbs () -> Integer
+    def search_product # rubocop:disable Metrics/MethodLength -- BFS lifecycle remains visible as one bounded worklist.
+      left_start = @left_machine.start
+      right_start = @right_machine.start
+      queue = [[left_start, right_start, []]] #: Array[[Machine::Configuration, Machine::Configuration, Array[String]]]
+      seen = { product_key(left_start, right_start) => true }
+      cursor = 0
+      truncated = false
+      alphabet = terminal_alphabet
+
+      while cursor < queue.length
+        left, right, tokens = queue.fetch(cursor)
+        cursor += 1
+        compare_configurations!(left, right, tokens)
+        next if tokens.length >= @max_tokens || both_rejected?(left, right)
+
+        alphabet.each do |token|
+          next_left = @left_machine.push(left, token)
+          next_right = @right_machine.push(right, token)
+          key = product_key(next_left, next_right)
+          next if seen[key]
+
+          if queue.length >= @max_configurations
+            truncated = true
+            next
+          end
+          seen[key] = true
+          queue << [next_left, next_right, tokens + [token]]
+        end
+      end
+      if truncated
+        raise BudgetExceeded.new(
+          result: "budget_exhausted", phase: "product_bfs", checked_configurations: cursor,
+          bounds: bounds, statement: CAVEAT
+        )
+      end
+
+      cursor
+    end
+
+    # @rbs (Array[String] tokens, method: String) -> void
+    def compare_tokens!(tokens, method:)
+      left = @left_machine.finish(@left_machine.run(tokens))
+      right = @right_machine.finish(@right_machine.run(tokens))
+      compare_results!(left, right, tokens, method)
+    end
+
+    # @rbs (Machine::Configuration left, Machine::Configuration right, Array[String] tokens) -> void
+    def compare_configurations!(left, right, tokens)
+      left_result = @left_machine.finish(left)
+      right_result = @right_machine.finish(right)
+      compare_results!(left_result, right_result, tokens, "bounded_product_bfs")
+    end
+
+    # @rbs (Machine::Configuration left, Machine::Configuration right, Array[String] tokens, String method) -> void
+    def compare_results!(left, right, tokens, method)
+      raise_language_difference(tokens, left.status, right.status, method) unless left.status == right.status
+      return unless left.status == :accepted && tree_requested?
+      return if tree_trace(@left, left, map_left: true) == tree_trace(@right, right, map_left: false)
+
+      raise Difference.new(
+        ibex_report: "equiv", schema_version: 1, result: "difference",
+        difference_kind: "tree", method: "#{method}_tree_trace", witness: tokens,
+        outcomes: { left: left.status, right: right.status },
+        bounds: bounds, statement: CAVEAT
+      )
+    end
+
+    # @rbs (Array[String] tokens, Symbol? left, Symbol? right, String method) -> bot
+    def raise_language_difference(tokens, left, right, method)
+      raise Difference.new(
+        ibex_report: "equiv", schema_version: 1, result: "difference",
+        difference_kind: "language", method: method, witness: tokens, outcomes: { left: left, right: right },
+        direction: left == :accepted ? "left_only" : "right_only",
+        bounds: bounds, statement: CAVEAT
+      )
+    end
+
+    # @rbs () -> bool
+    def structural_identity?
+      @left.algorithm == @right.algorithm &&
+        grammar_signature(@left.grammar, map_left: true) == grammar_signature(@right.grammar, map_left: false)
+    end
+
+    # @rbs () -> bool
+    def tree_structural_identity?
+      return true unless tree_requested?
+
+      tree_grammar_signature(@left.grammar) == tree_grammar_signature(@right.grammar)
+    end
+
+    # @rbs (IR::Grammar grammar) -> Array[tree_node_signature]
+    def tree_grammar_signature(grammar)
+      grammar.productions.filter_map { |production| node_signature(production.node) }
+    end
+
+    # @rbs (IR::node_annotation? node) -> tree_node_signature?
+    def node_signature(node)
+      node && [node.fetch(:name), node.fetch(:fields)]
+    end
+
+    # @rbs (IR::Automaton automaton, Machine::Configuration configuration, map_left: bool) -> Array[tree_trace_entry]
+    def tree_trace(automaton, configuration, map_left:)
+      configuration.reductions.map do |production_id|
+        production = automaton.grammar.productions.fetch(production_id)
+        lhs = symbol_name(automaton.grammar, production.lhs)
+        [
+          mapped_name(automaton.grammar, lhs, map_left: map_left),
+          production.rhs.map do |id|
+            mapped_name(automaton.grammar, symbol_name(automaton.grammar, id),
+                        map_left: map_left)
+          end,
+          node_signature(production.node)
+        ]
+      end
+    end
+
+    # @rbs (IR::Grammar grammar, map_left: bool) -> Hash[Symbol, Object?]
+    def grammar_signature(grammar, map_left:)
+      {
+        starts: grammar.starts.map { |name| mapped_name(grammar, name, map_left: map_left) },
+        recovery: recovery_signature(grammar, map_left: map_left),
+        terminals: terminal_signatures(grammar),
+        productions: production_signatures(grammar, map_left: map_left)
+      }
+    end
+
+    # @rbs (IR::Grammar grammar, map_left: bool) -> Hash[Symbol, Object?]
+    def recovery_signature(grammar, map_left:)
+      {
+        sync_tokens: grammar.recovery.fetch(:sync_tokens),
+        on_error_reduce: grammar.recovery.fetch(:on_error_reduce).map do |group|
+          group.map { |name| mapped_name(grammar, name, map_left: map_left) }
+        end
+      }
+    end
+
+    # @rbs (IR::Grammar grammar) -> Array[terminal_signature]
+    def terminal_signatures(grammar)
+      grammar.terminals.map do |symbol|
+        precedence = symbol.precedence
+        [symbol.name, precedence && [precedence.fetch(:associativity), precedence.fetch(:level)]]
+      end
+    end
+
+    # @rbs (IR::Grammar grammar, map_left: bool) -> Array[production_signature]
+    def production_signatures(grammar, map_left:)
+      grammar.productions.map { |production| production_signature(grammar, production, map_left: map_left) }
+    end
+
+    # @rbs (IR::Grammar grammar, IR::Production production, map_left: bool) -> production_signature
+    def production_signature(grammar, production, map_left:)
+      lhs = symbol_name(grammar, production.lhs)
+      rhs = production.rhs.map { |id| symbol_name(grammar, id) }
+      precedence = production.precedence_override
+      precedence_name = symbol_name(grammar, precedence) if precedence
+      [
+        mapped_name(grammar, lhs, map_left: map_left),
+        rhs.map { |name| mapped_name(grammar, name, map_left: map_left) },
+        precedence_name && mapped_name(grammar, precedence_name, map_left: map_left)
+      ]
+    end
+
+    # @rbs (IR::Grammar grammar, Integer id) -> String
+    def symbol_name(grammar, id)
+      symbol = grammar.symbol_by_id(id)
+      symbol ? symbol.name : id.to_s
+    end
+
+    # @rbs (IR::Grammar grammar, String name, map_left: bool) -> String
+    def mapped_name(grammar, name, map_left:)
+      symbol = grammar.symbol(name)
+      return name unless map_left && symbol&.nonterminal?
+
+      @rule_map.fetch(name, name)
+    end
+
+    # @rbs () -> void
+    def validate_rule_map!
+      left_names = @left.grammar.nonterminals.map(&:name)
+      right_names = @right.grammar.nonterminals.map(&:name)
+      unknown_left = @rule_map.keys - left_names
+      unknown_right = @rule_map.values - right_names
+      raise ArgumentError, "unknown left rules: #{unknown_left.join(', ')}" unless unknown_left.empty?
+      raise ArgumentError, "unknown right rules: #{unknown_right.join(', ')}" unless unknown_right.empty?
+      return if @rule_map.values.uniq.length == @rule_map.length
+
+      raise ArgumentError, "rule map must be one-to-one"
+    end
+
+    # @rbs () -> void
+    def verify_inputs!
+      { left: @left, right: @right }.each do |side, automaton|
+        result = Verify::Verifier.new(automaton).verify
+        next if result.valid?
+
+        raise Ibex::Error,
+              "(equiv):1:1: #{side} automaton failed independent verification: " \
+              "#{result.violations.first&.message}"
+      end
+    end
+
+    # @rbs () -> Array[String]
+    def terminal_alphabet
+      [@left, @right].flat_map do |automaton|
+        automaton.grammar.terminals.reject(&:reserved).map(&:name)
+      end.uniq.sort
+    end
+
+    # @rbs (Machine::Configuration left, Machine::Configuration right) -> Array[Object?]
+    def product_key(left, right)
+      key = [left.stack, left.status, left.actions, right.stack, right.status, right.actions]
+      key.push(left.reductions, right.reductions) if tree_requested?
+      key
+    end
+
+    # @rbs (Machine::Configuration left, Machine::Configuration right) -> bool
+    def both_rejected?(left, right)
+      left.status == :error && right.status == :error
+    end
+
+    # @rbs (structural: bool, samples: Integer, configurations: Integer) -> untyped
+    def successful_report(structural:, samples:, configurations:)
+      methods = if structural
+                  ["structural_comparison"]
+                else
+                  %w[structural_comparison bidirectional_sampling bounded_product_bfs]
+                end
+      IR.deep_freeze(
+        ibex_report: "equiv", schema_version: 1, result: "no_difference_within_bounds",
+        structural_identity: structural,
+        methods: methods,
+        rule_map: @rule_map,
+        tree: {
+          requested: tree_requested?,
+          result: tree_requested? ? "no_difference_within_bounds" : "not_checked"
+        },
+        checked: { samples: samples, product_configurations: configurations },
+        bounds: bounds, statement: CAVEAT
+      )
+    end
+
+    # @rbs () -> bool
+    def tree_requested? = !@rule_map.empty?
+
+    # @rbs () -> Hash[Symbol, Integer]
+    def bounds
+      {
+        sample_count: @sample_count, seed: @seed, max_tokens: @max_tokens,
+        max_configurations: @max_configurations, max_actions: @max_actions, max_stack: @max_stack
+      }
+    end
+
+    # @rbs (Ibex::Error error) -> bool
+    def sample_budget_error?(error)
+      error.message.match?(/(?:limit|maximum|budget).*(?:exceed|exhaust)|needs \d+ tokens/i)
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/ibex/error_messages/parser.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative "parser_v2"
+
+module Ibex
+  module ErrorMessages
+    # Strict line-oriented parser for the ibex-messages v1 and v2 formats.
+    class Parser
+      include ParserV2
+
+      ESCAPES = { "\\" => "\\", "n" => "\n", "t" => "\t", "r" => "\r" }.freeze
+
+      # @rbs @file: String
+      # @rbs @lines: Array[String]
+
+      # @rbs (String source, file: String) -> void
+      def initialize(source, file:)
+        @file = file
+        text = source.dup.force_encoding(Encoding::UTF_8)
+        fail_at(1, 1, "messages file must be valid UTF-8") unless text.valid_encoding?
+
+        @lines = text.lines(chomp: true)
+      end
+
+      # @rbs () -> Document
+      def parse
+        version = validate_header
+        return parse_v2 if version == 2
+
+        parse_v1
+      end
+
+      private
+
+      # @rbs () -> Document
+      def parse_v1
+        entries = [] #: Array[Entry]
+        declarations = {} #: Hash[Integer, Integer]
+        index = 1
+        while index < @lines.length
+          line = @lines.fetch(index)
+          if ignorable?(line)
+            index += 1
+            next
+          end
+
+          match = line.strip.match(/\A(state|removed)\s+([0-9]+)\z/)
+          fail_at(index + 1, column(line), top_level_expectation) unless match
+          state_text = match[2] || raise(Ibex::Error, "missing state number")
+          state = Integer(state_text, 10)
+          reject_duplicate(declarations, state, index, line)
+          declarations[state] = index + 1
+          entry, index = parse_entry(index, state, match[1] == "state" ? :active : :removed)
+          entries << entry
+        end
+        Document.new(version: 1, entries: entries)
+      end
+
+      # @rbs () -> Integer
+      def validate_header
+        header = @lines.first&.delete_prefix("\uFEFF")
+        return 1 if header == HEADER_V1
+        return 2 if header == HEADER
+
+        fail_at(1, 1, "expected #{HEADER.inspect} or #{HEADER_V1.inspect}")
+      end
+
+      # @rbs (Hash[Integer, Integer] declarations, Integer state, Integer index, String line) -> void
+      def reject_duplicate(declarations, state, index, line)
+        return unless declarations.key?(state)
+
+        fail_at(index + 1, column(line),
+                "duplicate state #{state}; first declared at line #{declarations.fetch(state)}")
+      end
+
+      # @rbs (Integer opening_index, Integer state, :active | :removed status) -> [Entry, Integer]
+      def parse_entry(opening_index, state, status)
+        message_lines = [] #: Array[String]
+        index = opening_index + 1
+        while index < @lines.length
+          line = @lines.fetch(index)
+          return close_entry(message_lines, opening_index, index, state, status) if line.strip == "end"
+
+          read_entry_line(message_lines, line, index)
+          index += 1
+        end
+        label = status == :active ? "state" : "removed"
+        fail_at(opening_index + 1, 1, "unterminated #{label} #{state} entry")
+      end
+
+      # @rbs (Array[String] message_lines, Integer opening_index, Integer index, Integer state,
+      #   :active | :removed status) -> [Entry, Integer]
+      def close_entry(message_lines, opening_index, index, state, status)
+        message = message_lines.empty? ? nil : message_lines.join("\n")
+        fail_at(opening_index + 1, 1, "message for state #{state} must not be empty") if message&.strip&.empty?
+
+        entry = Entry.new(state: state, status: status, message: message, line: opening_index + 1)
+        [entry, index + 1]
+      end
+
+      # @rbs (Array[String] message_lines, String line, Integer index) -> void
+      def read_entry_line(message_lines, line, index)
+        return if ignorable?(line)
+
+        unless line.start_with?("|")
+          fail_at(index + 1, column(line), "expected a `| ` message line, a comment, a blank line, or `end`")
+        end
+
+        content = line.delete_prefix("|")
+        content = content.delete_prefix(" ")
+        content_column = line.start_with?("| ") ? 3 : 2
+        message_lines << decode_line(content, index + 1, content_column)
+      end
+
+      # @rbs (String content, Integer line, Integer content_column) -> String
+      def decode_line(content, line, content_column)
+        decoded = +""
+        index = 0
+        while index < content.length
+          character = content[index] || raise(Ibex::Error, "missing message character")
+          unless character == "\\"
+            decoded << character
+            index += 1
+            next
+          end
+
+          escaped = content[index + 1]
+          fail_at(line, content_column + index, "trailing backslash in message line") unless escaped
+          replacement = ESCAPES[escaped]
+          fail_at(line, content_column + index, "unknown escape \\#{escaped}") unless replacement
+
+          decoded << replacement
+          index += 2
+        end
+        decoded
+      end
+
+      # @rbs (String line) -> bool
+      def ignorable?(line)
+        line.strip.empty? || line.lstrip.start_with?("#")
+      end
+
+      # @rbs () -> String
+      def top_level_expectation
+        "expected `state N`, `removed N`, a comment, or a blank line"
+      end
+
+      # @rbs (String line) -> Integer
+      def column(line)
+        (line.index(/\S/) || 0) + 1
+      end
+
+      # @rbs (Integer line, Integer column, String message) -> bot
+      def fail_at(line, column, message)
+        raise Ibex::Error, "#{@file}:#{line}:#{column}: #{message}"
+      end
+    end
+  end
+end