ibex 0.2.0 → 0.4.0

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

@@ -3,33 +3,33 @@
 module Ibex
   module IR
     module Validator
-      # Structural and referential validation for a versioned Automaton IR JSON object.
+      # 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 grammar_digest grammar states conflict_summary
+          ibex_ir schema_version algorithm entry_construction grammar_digest grammar states conflict_summary
         ].freeze #: Array[String]
-        V2_ROOT_OPTIONAL = %w[entry_states].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: Hash[String, untyped]
-        # @rbs @states_by_id: Hash[Integer, Hash[String, untyped]]
+        # @rbs @data: json_object
+        # @rbs @states_by_id: Hash[Integer, json_object]
         # @rbs @grammar: GrammarDocument
         # @rbs @version: Integer
 
-        # @rbs (Hash[String, untyped] data, ?version: Integer) -> void
+        # @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, Hash[String, untyped]]
+          @states_by_id = {} #: Hash[Integer, json_object]
         end
 
         # @rbs () -> self
         def validate
-          record(@data, "$", ROOT_REQUIRED, @version >= 2 ? V2_ROOT_OPTIONAL : [])
+          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])
@@ -37,6 +37,7 @@ module Ibex
           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
@@ -58,11 +59,31 @@ module Ibex
           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|
-            nonnegative_integer(state, "$.entry_states.#{name}")
-            invalid("$.entry_states.#{name}", "references missing state #{state}") unless @states_by_id[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")
@@ -95,7 +116,7 @@ module Ibex
           end
         end
 
-        # @rbs (untyped value, String path) -> void
+        # @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}]"
@@ -106,7 +127,7 @@ module Ibex
           end
         end
 
-        # @rbs (Integer production_id, untyped dot_value, String path) -> void
+        # @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
@@ -115,10 +136,11 @@ module Ibex
           end
           production = @grammar.productions_by_id[production_id]
           invalid("#{path}.production", "references missing production id #{production_id}") unless production
-          invalid("#{path}.dot", "exceeds production #{production_id} length") if dot > production["rhs"].length
+          rhs = array(production["rhs"], "#{path}.production.rhs")
+          invalid("#{path}.dot", "exceeds production #{production_id} length") if dot > rhs.length
         end
 
-        # @rbs (untyped value, String path) -> void
+        # @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}]")
@@ -128,28 +150,28 @@ module Ibex
           end
         end
 
-        # @rbs (untyped value, String path) -> void
+        # @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 (untyped value, String path) -> void
+        # @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 (untyped value, String path) -> void
+        # @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 (untyped value, String path, ?kind: String?) { (untyped, String, Hash[String, untyped]) -> void } -> void
+        # @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)
@@ -160,13 +182,13 @@ module Ibex
           end
         end
 
-        # @rbs (untyped value, String path) -> void
+        # @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 (untyped value, String path, ?nullable: bool) -> void
+        # @rbs (json_value value, String path, ?nullable: bool) -> void
         def validate_parser_action(value, path, nullable: false)
           return if nullable && value.nil?
 
@@ -182,13 +204,13 @@ module Ibex
           validate_production_reference(action["production"], "#{path}.production") if type == "reduce"
         end
 
-        # @rbs (untyped value, String path) -> void
+        # @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 (untyped value, String path) -> void
+        # @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}]"
@@ -203,7 +225,7 @@ module Ibex
           end
         end
 
-        # @rbs (Hash[String, untyped] conflict, String path) -> void
+        # @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")
@@ -215,11 +237,13 @@ module Ibex
           validate_conflict_entries(conflict, path)
         end
 
-        # @rbs (Hash[String, untyped] conflict, String path) -> void
+        # @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")
+          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}]")
@@ -233,7 +257,7 @@ module Ibex
           validate_conflict_entries(conflict, path)
         end
 
-        # @rbs (Hash[String, untyped] conflict, String path) -> void
+        # @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")]
@@ -248,14 +272,14 @@ module Ibex
           boolean(conflict["composite"], "#{path}.composite") if conflict.key?("composite")
         end
 
-        # @rbs (untyped value, String path) -> void
+        # @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 (untyped value, String path) -> void
+        # @rbs (json_value value, String path) -> void
         def validate_conflict_symbol(value, path)
           name = string(value, path)
           symbol = @grammar.symbols_by_name[name]
@@ -263,7 +287,7 @@ module Ibex
           invalid(path, "must reference a terminal") unless symbol["kind"] == "terminal"
         end
 
-        # @rbs (untyped value, String path, ?reductions: Array[Integer]?) -> void
+        # @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)
@@ -298,9 +322,14 @@ module Ibex
           validate_expectation(summary, path)
         end
 
-        # @rbs (Hash[String, untyped] summary, String path) -> void
+        # @rbs (json_object summary, String path) -> void
         def validate_conflict_counts(summary, path)
-          conflicts = @states_by_id.values.flat_map { |state| state["conflicts"] }
+          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" },
@@ -315,9 +344,10 @@ module Ibex
           end
         end
 
-        # @rbs (Hash[String, untyped] summary, String path) -> void
+        # @rbs (json_object summary, String path) -> void
         def validate_expectation(summary, path)
-          grammar_expect = @data.fetch("grammar").fetch("expect")
+          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
@@ -326,7 +356,7 @@ module Ibex
             invalid("#{path}.expectation_met", "must be #{expected_met} for the recorded shift/reduce count")
           end
 
-          grammar_expect_rr = @data.fetch("grammar")["expect_rr"]
+          grammar_expect_rr = grammar["expect_rr"]
           return if grammar_expect_rr.nil?
 
           unless summary["expected_rr"] == grammar_expect_rr

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

@@ -3,15 +3,19 @@
 module Ibex
   module IR
     module Validator
-      # Shared JSON-shape checks for the two version-1 IR documents.
+      # @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 (untyped value, String path, Array[String] required, ?Array[String] optional) -> Hash[String, untyped]
+        # @rbs (json_value value, String path, Array[String] required, ?Array[String] optional) -> json_object
         def record(value, path, required, optional = [])
-          object(value, path)
+          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
@@ -19,97 +23,111 @@ module Ibex
           value
         end
 
-        # @rbs (untyped value, String path) -> Hash[String, untyped]
+        # @rbs (json_value value, String path) -> json_object
         def object(value, path)
-          invalid(path, "must be an object") unless value.is_a?(Hash)
-          value
+          if value.is_a?(Hash)
+            object = value #: json_object
+            return object
+          end
+
+          invalid(path, "must be an object")
         end
 
-        # @rbs (untyped value, String path) -> Array[untyped]
+        # @rbs (json_value value, String path) -> Array[json_value]
         def array(value, path)
-          invalid(path, "must be an array") unless value.is_a?(Array)
-          value
+          if value.is_a?(Array)
+            array = value #: Array[json_value]
+            return array
+          end
+
+          invalid(path, "must be an array")
         end
 
-        # @rbs (untyped value, String path) -> String
+        # @rbs (json_value value, String path) -> String
         def string(value, path)
-          invalid(path, "must be a string") unless value.is_a?(String)
-          value
+          return value if value.is_a?(String)
+
+          invalid(path, "must be a string")
         end
 
-        # @rbs (untyped value, String path) -> String
+        # @rbs (json_value value, String path) -> String
         def nonempty_string(value, path)
-          string(value, path)
+          value = string(value, path)
           invalid(path, "must not be empty") if value.empty?
           value
         end
 
-        # @rbs (untyped value, String path) -> Integer
+        # @rbs (json_value value, String path) -> Integer
         def integer(value, path)
-          invalid(path, "must be an integer") unless value.is_a?(Integer)
-          value
+          return value if value.is_a?(Integer)
+
+          invalid(path, "must be an integer")
         end
 
-        # @rbs (untyped value, String path) -> Integer
+        # @rbs (json_value value, String path) -> Integer
         def nonnegative_integer(value, path)
-          integer(value, path)
+          value = integer(value, path)
           invalid(path, "must be greater than or equal to 0") if value.negative?
           value
         end
 
-        # @rbs (untyped value, String path) -> bool
+        # @rbs (json_value value, String path) -> bool
         def boolean(value, path)
-          invalid(path, "must be a boolean") unless [true, false].include?(value)
-          value
+          if [true, false].include?(value)
+            result = value #: bool
+            return result
+          end
+
+          invalid(path, "must be a boolean")
         end
 
-        # @rbs (untyped value, String path, untyped expected) -> void
+        # @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 (untyped value, String path, Array[String] values) -> String
+        # @rbs (json_value value, String path, Array[String] values) -> String
         def enum(value, path, values)
-          string(value, path)
+          value = string(value, path)
           invalid(path, "must be one of #{values.join(', ')}") unless values.include?(value)
           value
         end
 
-        # @rbs (untyped value, String path, ?nullable: bool) -> void
+        # @rbs (json_value value, String path, ?nullable: bool) -> void
         def location(value, path, nullable: true)
           return if nullable && value.nil?
 
-          record(value, path, %w[file line column])
+          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 (untyped value, String path) -> Integer
+        # @rbs (json_value value, String path) -> Integer
         def positive_integer(value, path)
-          integer(value, path)
+          value = integer(value, path)
           invalid(path, "must be greater than or equal to 1") unless value.positive?
           value
         end
 
-        # @rbs (untyped value, String path) -> String?
+        # @rbs (json_value value, String path) -> String?
         def nullable_string(value, path)
           return nil if value.nil?
 
           string(value, path)
         end
 
-        # @rbs (untyped value, String path) -> void
+        # @rbs (json_value value, String path) -> void
         def metadata(value, path)
           return if value.nil?
 
-          string(value, path)
+          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 (Hash[String, untyped] value, String key, String path) -> untyped
+        # @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