ibex 0.1.0 → 0.3.0

data/lib/ibex/ir/validator/automaton.rb

@@ -0,0 +1,375 @@
+# frozen_string_literal: true
+
+module Ibex
+  module IR
+    module Validator
+      # Structural and referential validation for a current Automaton IR JSON object.
+      # rubocop:disable Metrics/ClassLength -- inline type contracts accompany one cohesive document validator.
+      class AutomatonDocument < Base
+        ROOT_REQUIRED = %w[
+          ibex_ir schema_version algorithm entry_construction grammar_digest grammar states conflict_summary
+        ].freeze #: Array[String]
+        ROOT_OPTIONAL = %w[entry_states].freeze #: Array[String]
+        STATE_REQUIRED = %w[id items transitions actions gotos default_action conflicts].freeze #: Array[String]
+        ACTION_TYPES = %w[shift reduce accept error].freeze #: Array[String]
+        RESOLUTION_KINDS = %w[definition_order default_shift precedence associativity].freeze #: Array[String]
+
+        # @rbs @data: json_object
+        # @rbs @states_by_id: Hash[Integer, json_object]
+        # @rbs @grammar: GrammarDocument
+        # @rbs @version: Integer
+
+        # @rbs (json_object data, ?version: Integer) -> void
+        def initialize(data, version: data.fetch("schema_version"))
+          super()
+          @data = data
+          @version = version
+          @states_by_id = {} #: Hash[Integer, json_object]
+        end
+
+        # @rbs () -> self
+        def validate
+          record(@data, "$", ROOT_REQUIRED, ROOT_OPTIONAL)
+          literal(@data["ibex_ir"], "$.ibex_ir", "automaton")
+          literal(@data["schema_version"], "$.schema_version", @version)
+          enum(@data["algorithm"], "$.algorithm", %w[slr lalr1 ielr1 lr1])
+          validate_digest
+          grammar = object(@data["grammar"], "$.grammar")
+          literal(grammar["schema_version"], "$.grammar.schema_version", @version)
+          @grammar = GrammarDocument.new(grammar, path: "$.grammar", version: @version).validate
+          validate_construction_contract(grammar)
+          validate_state_records
+          validate_entry_states
+          validate_state_contents
+          validate_conflict_summary
+          self
+        end
+
+        private
+
+        # @rbs () -> void
+        def validate_entry_states
+          value = @data["entry_states"]
+          if value.nil?
+            invalid("$.entry_states", "is required for multiple start symbols") if @data.dig("grammar", "starts")
+            return
+          end
+
+          entries = object(value, "$.entry_states")
+          expected = @data.dig("grammar", "starts") || [@data.dig("grammar", "start")]
+          invalid("$.entry_states", "keys must equal grammar starts in order") unless entries.keys == expected
+          entries.each do |name, state|
+            state_id = nonnegative_integer(state, "$.entry_states.#{name}")
+            invalid("$.entry_states.#{name}", "references missing state #{state_id}") unless @states_by_id[state_id]
+          end
+        end
+
+        # @rbs (Hash[String, untyped] grammar) -> void
+        def validate_construction_contract(grammar)
+          entry_construction = enum(
+            @data["entry_construction"], "$.entry_construction", %w[shared isolated]
+          )
+          contract = grammar.fetch("parser_contract")
+          algorithm = contract.fetch("algorithm")
+          expected_algorithm = { "lalr" => "lalr1", "ielr" => "ielr1" }.fetch(
+            algorithm["value"], algorithm["value"]
+          )
+          if algorithm["explicit"] && @data["algorithm"] != expected_algorithm
+            invalid("$.algorithm", "must match the embedded parser contract")
+          end
+
+          entries = contract.fetch("entries")
+          return unless entries["explicit"] && entry_construction != entries["value"]
+
+          invalid("$.entry_construction", "must match the embedded parser contract")
+        end
+
+        # @rbs () -> void
+        def validate_digest
+          digest = string(@data["grammar_digest"], "$.grammar_digest")
+          invalid("$.grammar_digest", "must be a sha256 digest") unless digest.match?(/\Asha256:[0-9a-f]{64}\z/)
+        end
+
+        # @rbs () -> void
+        def validate_state_records
+          states = array(@data["states"], "$.states")
+          invalid("$.states", "must contain at least one state") if states.empty?
+          states.each_with_index do |value, index|
+            path = "$.states[#{index}]"
+            state = record(value, path, STATE_REQUIRED)
+            id = nonnegative_integer(state["id"], "#{path}.id")
+            invalid("#{path}.id", "must equal its array index #{index}") unless id == index
+            @states_by_id[id] = state
+          end
+        end
+
+        # @rbs () -> void
+        def validate_state_contents
+          @states_by_id.each do |id, state|
+            path = "$.states[#{id}]"
+            validate_items(state["items"], "#{path}.items")
+            validate_transitions(state["transitions"], "#{path}.transitions")
+            validate_actions(state["actions"], "#{path}.actions")
+            validate_gotos(state["gotos"], "#{path}.gotos")
+            validate_parser_action(state["default_action"], "#{path}.default_action", nullable: true)
+            validate_conflicts(state["conflicts"], "#{path}.conflicts")
+          end
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_items(value, path)
+          array(value, path).each_with_index do |item, index|
+            item_path = "#{path}[#{index}]"
+            item = record(item, item_path, %w[production dot lookaheads])
+            production = integer(item["production"], "#{item_path}.production")
+            validate_item_production(production, item["dot"], item_path)
+            validate_lookaheads(item["lookaheads"], "#{item_path}.lookaheads")
+          end
+        end
+
+        # @rbs (Integer production_id, json_value dot_value, String path) -> void
+        def validate_item_production(production_id, dot_value, path)
+          dot = nonnegative_integer(dot_value, "#{path}.dot")
+          if production_id == -1
+            invalid("#{path}.dot", "must not exceed 1 for the augmented production") if dot > 1
+            return
+          end
+          production = @grammar.productions_by_id[production_id]
+          invalid("#{path}.production", "references missing production id #{production_id}") unless production
+          rhs = array(production["rhs"], "#{path}.production.rhs")
+          invalid("#{path}.dot", "exceeds production #{production_id} length") if dot > rhs.length
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_lookaheads(value, path)
+          array(value, path).each_with_index do |name, index|
+            name = string(name, "#{path}[#{index}]")
+            symbol = @grammar.symbols_by_name[name]
+            invalid("#{path}[#{index}]", "references missing symbol #{name.inspect}") unless symbol
+            invalid("#{path}[#{index}]", "must reference a terminal") unless symbol["kind"] == "terminal"
+          end
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_transitions(value, path)
+          symbol_map(value, path) do |target, target_path, _symbol|
+            validate_state_reference(target, target_path)
+          end
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_actions(value, path)
+          symbol_map(value, path, kind: "terminal") do |action, action_path, _symbol|
+            validate_parser_action(action, action_path)
+          end
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_gotos(value, path)
+          symbol_map(value, path, kind: "nonterminal") do |target, target_path, _symbol|
+            validate_state_reference(target, target_path)
+          end
+        end
+
+        # @rbs (json_value value, String path, ?kind: String?) { (json_value, String, json_object) -> void } -> void
+        def symbol_map(value, path, kind: nil, &block)
+          object(value, path).each do |name, item|
+            item_path = child_path(path, name)
+            symbol = @grammar.symbols_by_name[name]
+            invalid(item_path, "references missing symbol #{name.inspect}") unless symbol
+            invalid(item_path, "must reference a #{kind}") if kind && symbol["kind"] != kind
+            block.call(item, item_path, symbol)
+          end
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_state_reference(value, path)
+          id = nonnegative_integer(value, path)
+          invalid(path, "references missing state id #{id}") unless @states_by_id.key?(id)
+        end
+
+        # @rbs (json_value value, String path, ?nullable: bool) -> void
+        def validate_parser_action(value, path, nullable: false)
+          return if nullable && value.nil?
+
+          action = object(value, path)
+          type = enum(field(action, "type", path), "#{path}.type", ACTION_TYPES)
+          required = case type
+                     when "shift" then %w[type state]
+                     when "reduce" then %w[type production]
+                     else %w[type]
+                     end
+          record(action, path, required)
+          validate_state_reference(action["state"], "#{path}.state") if type == "shift"
+          validate_production_reference(action["production"], "#{path}.production") if type == "reduce"
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_production_reference(value, path)
+          id = nonnegative_integer(value, path)
+          invalid(path, "references missing production id #{id}") unless @grammar.productions_by_id.key?(id)
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_conflicts(value, path)
+          array(value, path).each_with_index do |conflict, index|
+            conflict_path = "#{path}[#{index}]"
+            conflict = object(conflict, conflict_path)
+            type = enum(field(conflict, "type", conflict_path), "#{conflict_path}.type",
+                        %w[shift_reduce reduce_reduce])
+            if type == "shift_reduce"
+              validate_shift_reduce(conflict, conflict_path)
+            else
+              validate_reduce_reduce(conflict, conflict_path)
+            end
+          end
+        end
+
+        # @rbs (json_object conflict, String path) -> void
+        def validate_shift_reduce(conflict, path)
+          record(conflict, path, %w[type symbol shift_to reduce resolution], %w[midrule_origins entries composite])
+          validate_conflict_symbol(conflict["symbol"], "#{path}.symbol")
+          validate_state_reference(conflict["shift_to"], "#{path}.shift_to")
+          validate_production_reference(conflict["reduce"], "#{path}.reduce")
+          validate_resolution(conflict["resolution"], "#{path}.resolution")
+          validate_midrule_origins(conflict["midrule_origins"], "#{path}.midrule_origins") if
+            conflict.key?("midrule_origins")
+          validate_conflict_entries(conflict, path)
+        end
+
+        # @rbs (json_object conflict, String path) -> void
+        def validate_reduce_reduce(conflict, path)
+          record(conflict, path, %w[type symbol reductions resolution], %w[midrule_origins entries composite])
+          validate_conflict_symbol(conflict["symbol"], "#{path}.symbol")
+          reductions = array(conflict["reductions"], "#{path}.reductions").map.with_index do |id, index|
+            nonnegative_integer(id, "#{path}.reductions[#{index}]")
+          end
+          invalid("#{path}.reductions", "must contain at least two productions") if reductions.length < 2
+          reductions.each_with_index do |id, index|
+            validate_production_reference(id, "#{path}.reductions[#{index}]")
+          end
+          if reductions.uniq.length != reductions.length
+            invalid("#{path}.reductions", "must contain unique production ids")
+          end
+          validate_resolution(conflict["resolution"], "#{path}.resolution", reductions: reductions)
+          validate_midrule_origins(conflict["midrule_origins"], "#{path}.midrule_origins") if
+            conflict.key?("midrule_origins")
+          validate_conflict_entries(conflict, path)
+        end
+
+        # @rbs (json_object conflict, String path) -> void
+        def validate_conflict_entries(conflict, path)
+          if conflict.key?("entries")
+            starts = @data.dig("grammar", "starts") || [@data.dig("grammar", "start")]
+            entries = array(conflict["entries"], "#{path}.entries")
+            invalid("#{path}.entries", "must not be empty") if entries.empty?
+            entries.each_with_index do |name, index|
+              name = nonempty_string(name, "#{path}.entries[#{index}]")
+              invalid("#{path}.entries[#{index}]", "is not a grammar start symbol") unless starts.include?(name)
+            end
+            invalid("#{path}.entries", "must be unique") unless entries.uniq.length == entries.length
+          end
+          boolean(conflict["composite"], "#{path}.composite") if conflict.key?("composite")
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_midrule_origins(value, path)
+          origins = array(value, path)
+          invalid(path, "must not be empty") if origins.empty?
+          origins.each_with_index { |origin, index| location(origin, "#{path}[#{index}]") }
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def validate_conflict_symbol(value, path)
+          name = string(value, path)
+          symbol = @grammar.symbols_by_name[name]
+          invalid(path, "references missing symbol #{name.inspect}") unless symbol
+          invalid(path, "must reference a terminal") unless symbol["kind"] == "terminal"
+        end
+
+        # @rbs (json_value value, String path, ?reductions: Array[Integer]?) -> void
+        def validate_resolution(value, path, reductions: nil)
+          resolution = record(value, path, %w[by chose], %w[associativity])
+          enum(resolution["by"], "#{path}.by", RESOLUTION_KINDS)
+          if reductions
+            chosen = resolution["chose"]
+            validate_production_reference(chosen, "#{path}.chose")
+            invalid("#{path}.chose", "must be one of the reductions") unless reductions.include?(chosen)
+          else
+            enum(resolution["chose"], "#{path}.chose", %w[shift reduce error])
+          end
+          return unless resolution.key?("associativity")
+
+          enum(resolution["associativity"], "#{path}.associativity", %w[left right nonassoc])
+        end
+
+        # @rbs () -> void
+        def validate_conflict_summary
+          path = "$.conflict_summary"
+          summary = record(
+            @data["conflict_summary"], path, %w[sr resolved_sr rr expected_sr expectation_met],
+            %w[expected_rr rr_expectation_met]
+          )
+          %w[sr resolved_sr rr expected_sr].each do |key|
+            nonnegative_integer(summary[key], "#{path}.#{key}")
+          end
+          boolean(summary["expectation_met"], "#{path}.expectation_met")
+          if summary.key?("expected_rr") || summary.key?("rr_expectation_met")
+            nonnegative_integer(summary["expected_rr"], "#{path}.expected_rr")
+            boolean(summary["rr_expectation_met"], "#{path}.rr_expectation_met")
+          end
+          validate_conflict_counts(summary, path)
+          validate_expectation(summary, path)
+        end
+
+        # @rbs (json_object summary, String path) -> void
+        def validate_conflict_counts(summary, path)
+          conflicts = @states_by_id.values.flat_map do |state|
+            array(state["conflicts"], "$.states.conflicts").map do |conflict|
+              record = conflict #: json_object
+              record
+            end
+          end
+          shift_reduce = conflicts.select { |conflict| conflict["type"] == "shift_reduce" }
+          counts = {
+            "sr" => shift_reduce.count { |conflict| conflict.dig("resolution", "by") == "default_shift" },
+            "resolved_sr" => shift_reduce.count { |conflict| conflict.dig("resolution", "by") != "default_shift" },
+            "rr" => conflicts.count { |conflict| conflict["type"] == "reduce_reduce" }
+          }
+          counts.each do |key, actual|
+            next if summary[key] == actual
+
+            label = key == "rr" ? "reduce/reduce" : "shift/reduce"
+            invalid("#{path}.#{key}", "must equal the #{actual} recorded #{label} conflicts")
+          end
+        end
+
+        # @rbs (json_object summary, String path) -> void
+        def validate_expectation(summary, path)
+          grammar = @data.fetch("grammar") #: json_object
+          grammar_expect = grammar.fetch("expect")
+          unless summary["expected_sr"] == grammar_expect
+            invalid("#{path}.expected_sr", "must equal embedded grammar expect #{grammar_expect}")
+          end
+          expected_met = summary["sr"] == summary["expected_sr"]
+          unless summary["expectation_met"] == expected_met
+            invalid("#{path}.expectation_met", "must be #{expected_met} for the recorded shift/reduce count")
+          end
+
+          grammar_expect_rr = grammar["expect_rr"]
+          return if grammar_expect_rr.nil?
+
+          unless summary["expected_rr"] == grammar_expect_rr
+            invalid("#{path}.expected_rr", "must equal embedded grammar expect_rr #{grammar_expect_rr}")
+          end
+          rr_expected_met = summary["rr"] == summary["expected_rr"]
+          return if summary["rr_expectation_met"] == rr_expected_met
+
+          invalid("#{path}.rr_expectation_met",
+                  "must be #{rr_expected_met} for the recorded reduce/reduce count")
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end

data/lib/ibex/ir/validator/base.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Ibex
+  module IR
+    module Validator
+      # @rbs!
+      #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+      #   type json_object = Hash[String, json_value]
+
+      # Shared JSON-shape checks for current IR documents.
+      class Base
+        POSITION = "(ir):1:1"
+
+        private
+
+        # @rbs (json_value value, String path, Array[String] required, ?Array[String] optional) -> json_object
+        def record(value, path, required, optional = [])
+          value = object(value, path)
+          missing = required.reject { |key| value.key?(key) }
+          invalid(path, "is missing required field #{missing.first.inspect}") unless missing.empty?
+          unknown = value.keys - required - optional
+          invalid(path, "has unsupported field #{unknown.first.inspect}") unless unknown.empty?
+          value
+        end
+
+        # @rbs (json_value value, String path) -> json_object
+        def object(value, path)
+          if value.is_a?(Hash)
+            object = value #: json_object
+            return object
+          end
+
+          invalid(path, "must be an object")
+        end
+
+        # @rbs (json_value value, String path) -> Array[json_value]
+        def array(value, path)
+          if value.is_a?(Array)
+            array = value #: Array[json_value]
+            return array
+          end
+
+          invalid(path, "must be an array")
+        end
+
+        # @rbs (json_value value, String path) -> String
+        def string(value, path)
+          return value if value.is_a?(String)
+
+          invalid(path, "must be a string")
+        end
+
+        # @rbs (json_value value, String path) -> String
+        def nonempty_string(value, path)
+          value = string(value, path)
+          invalid(path, "must not be empty") if value.empty?
+          value
+        end
+
+        # @rbs (json_value value, String path) -> Integer
+        def integer(value, path)
+          return value if value.is_a?(Integer)
+
+          invalid(path, "must be an integer")
+        end
+
+        # @rbs (json_value value, String path) -> Integer
+        def nonnegative_integer(value, path)
+          value = integer(value, path)
+          invalid(path, "must be greater than or equal to 0") if value.negative?
+          value
+        end
+
+        # @rbs (json_value value, String path) -> bool
+        def boolean(value, path)
+          if [true, false].include?(value)
+            result = value #: bool
+            return result
+          end
+
+          invalid(path, "must be a boolean")
+        end
+
+        # @rbs (json_value value, String path, json_value expected) -> void
+        def literal(value, path, expected)
+          invalid(path, "must be #{expected.inspect}") unless value == expected
+        end
+
+        # @rbs (json_value value, String path, Array[String] values) -> String
+        def enum(value, path, values)
+          value = string(value, path)
+          invalid(path, "must be one of #{values.join(', ')}") unless values.include?(value)
+          value
+        end
+
+        # @rbs (json_value value, String path, ?nullable: bool) -> void
+        def location(value, path, nullable: true)
+          return if nullable && value.nil?
+
+          value = record(value, path, %w[file line column])
+          string(value["file"], "#{path}.file")
+          positive_integer(value["line"], "#{path}.line")
+          positive_integer(value["column"], "#{path}.column")
+        end
+
+        # @rbs (json_value value, String path) -> Integer
+        def positive_integer(value, path)
+          value = integer(value, path)
+          invalid(path, "must be greater than or equal to 1") unless value.positive?
+          value
+        end
+
+        # @rbs (json_value value, String path) -> String?
+        def nullable_string(value, path)
+          return nil if value.nil?
+
+          string(value, path)
+        end
+
+        # @rbs (json_value value, String path) -> void
+        def metadata(value, path)
+          return if value.nil?
+
+          value = string(value, path)
+          invalid(path, "must not be empty") if value.strip.empty?
+          invalid(path, "must be a single line") if value.match?(/[\r\n]/)
+          invalid(path, "must not contain control characters") if value.match?(/[[:cntrl:]]/)
+        end
+
+        # @rbs (json_object value, String key, String path) -> json_value
+        def field(value, key, path)
+          value.fetch(key) { invalid(path, "is missing required field #{key.inspect}") }
+        end
+
+        # @rbs (String path, String key) -> String
+        def child_path(path, key)
+          key.match?(/\A[$A-Za-z_][$A-Za-z0-9_]*\z/) ? "#{path}.#{key}" : "#{path}[#{key.inspect}]"
+        end
+
+        # @rbs (String path, String message) -> bot
+        def invalid(path, message)
+          raise Ibex::Error, "#{POSITION}: #{path} #{message}"
+        end
+      end
+    end
+  end
+end