ibex 0.2.0 → 0.4.0

data/lib/ibex/ir/automaton_ir.rb

@@ -16,7 +16,7 @@ module Ibex
         freeze
       end
 
-      # @rbs (Grammar grammar) -> Hash[Symbol, untyped]
+      # @rbs (Grammar grammar) -> Hash[Symbol, Object?]
       def to_h(grammar)
         { production: @production, dot: @dot,
           lookaheads: @lookaheads.map do |id|
@@ -50,7 +50,7 @@ module Ibex
         freeze
       end
 
-      # @rbs (Grammar grammar) -> Hash[Symbol, untyped]
+      # @rbs (Grammar grammar) -> Hash[Symbol, Object?]
       def to_h(grammar)
         { id: @id, items: @items.map { |item| item.to_h(grammar) },
           transitions: named_keys(@transitions, grammar), actions: named_keys(@actions, grammar),
@@ -59,7 +59,7 @@ module Ibex
 
       private
 
-      # @rbs (Hash[Integer, untyped] values, Grammar grammar) -> Hash[String, untyped]
+      # @rbs (Hash[Integer, Object?] values, Grammar grammar) -> Hash[String, Object?]
       def named_keys(values, grammar)
         values.to_h do |symbol_id, value|
           symbol = grammar.symbol_by_id(symbol_id) || raise(Ibex::Error, "missing grammar symbol id #{symbol_id}")
@@ -77,42 +77,55 @@ module Ibex
       attr_reader :entry_states #: Hash[String, Integer]
       attr_reader :conflict_summary #: conflict_summary
       attr_reader :schema_version #: Integer
+      attr_reader :entry_construction #: String
 
       # @rbs (grammar: Grammar, states: Array[AutomatonState], conflict_summary: conflict_summary,
-      #   ?algorithm: String, ?grammar_digest: String?, ?schema_version: Integer,
-      #   ?entry_states: Hash[String, Integer]?) -> void
+      #   ?algorithm: String, ?grammar_digest: String?, ?entry_states: Hash[String, Integer]?,
+      #   ?entry_construction: String) -> void
       def initialize(grammar:, states:, conflict_summary:, algorithm: "lalr1", grammar_digest: nil,
-                     schema_version: SCHEMA_VERSION, entry_states: nil)
-        unless SUPPORTED_SCHEMA_VERSIONS.include?(schema_version)
-          raise Ibex::Error, "unsupported automaton schema_version #{schema_version.inspect}"
-        end
+                     entry_states: nil, entry_construction: "shared")
+        initialize_current(
+          grammar: grammar, states: states, conflict_summary: conflict_summary, algorithm: algorithm,
+          grammar_digest: grammar_digest, entry_states: entry_states, entry_construction: entry_construction
+        )
+      end
 
-        grammar = Migration.to_v2(grammar) if schema_version >= 2 && grammar.schema_version != schema_version
-        raise Ibex::Error, "automaton migration did not produce a grammar" unless grammar.is_a?(Grammar)
-        unless grammar.schema_version == schema_version
-          raise Ibex::Error,
-                "automaton schema_version #{schema_version} requires Grammar IR v#{schema_version}, " \
-                "got v#{grammar.schema_version}"
+      # @rbs (grammar: Grammar, states: Array[AutomatonState], conflict_summary: conflict_summary,
+      #   algorithm: String, grammar_digest: String?, entry_states: Hash[String, Integer]?,
+      #   entry_construction: String) -> void
+      def initialize_current(grammar:, states:, conflict_summary:, algorithm:, grammar_digest:, entry_states:,
+                             entry_construction:)
+        unless grammar.schema_version == SCHEMA_VERSION
+          raise Ibex::Error, "automaton requires the current Grammar IR format"
         end
 
         @algorithm = algorithm.freeze
         @grammar = grammar
-        @grammar_digest = (grammar_digest || digest_for(grammar)).freeze
+        expected_digest = digest_for(grammar)
+        if grammar_digest && grammar_digest != expected_digest
+          raise Ibex::Error,
+                "(ir):1:1: $.grammar_digest does not match the embedded grammar; expected #{expected_digest.inspect}"
+        end
+        @grammar_digest = (grammar_digest || expected_digest).freeze
         @states = states.freeze
         @entry_states = IR.deep_freeze(entry_states || { grammar.start => 0 })
         validate_entry_states
         @conflict_summary = IR.deep_freeze(conflict_summary)
-        @schema_version = schema_version
+        @schema_version = SCHEMA_VERSION
+        @entry_construction = validate_entry_construction(entry_construction)
+        validate_parser_contract
         freeze
       end
+      private :initialize_current
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         value = { ibex_ir: "automaton", schema_version: @schema_version, algorithm: @algorithm,
                   grammar_digest: @grammar_digest, grammar: @grammar.to_h,
                   states: @states.map { |state| state.to_h(@grammar) },
-                  conflict_summary: @conflict_summary } #: Hash[Symbol, untyped]
+                  conflict_summary: @conflict_summary } #: Hash[Symbol, Object?]
         value[:entry_states] = @entry_states unless @entry_states == { @grammar.start => 0 }
+        value[:entry_construction] = @entry_construction
         value
       end
 
@@ -137,6 +150,35 @@ module Ibex
         require "digest"
         "sha256:#{Digest::SHA256.hexdigest(IR::Serialize.dump(grammar))}"
       end
+
+      # @rbs (String value) -> String
+      def validate_entry_construction(value)
+        raise Ibex::Error, "entry construction must be shared or isolated" unless %w[shared isolated].include?(value)
+
+        value.dup.freeze
+      end
+
+      # @rbs () -> void
+      def validate_parser_contract
+        contract = @grammar.parser_contract
+        validate_parser_algorithm(contract)
+        validate_parser_entries(contract)
+      end
+
+      # @rbs (ParserContract contract) -> void
+      def validate_parser_algorithm(contract)
+        selected_algorithm = { "lalr1" => :lalr, "ielr1" => :ielr }.fetch(@algorithm, @algorithm.to_sym)
+        return unless contract.algorithm.explicit && contract.algorithm.value != selected_algorithm
+
+        raise Ibex::Error, "automaton algorithm conflicts with the embedded parser contract"
+      end
+
+      # @rbs (ParserContract contract) -> void
+      def validate_parser_entries(contract)
+        return unless contract.entries.explicit && contract.entries.value.to_s != @entry_construction
+
+        raise Ibex::Error, "automaton entry construction conflicts with the embedded parser contract"
+      end
     end
   end
 end

data/lib/ibex/ir/grammar_ir.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "parser_contract"
+
 module Ibex
   module IR
-    SCHEMA_VERSION = 2
-    SUPPORTED_SCHEMA_VERSIONS = [1, 2].freeze #: Array[Integer]
+    # Grammar IR has one active wire format.  A future incompatible format
+    # change may advance this number, but the runtime never treats old
+    # formats as an alternate compatibility surface.
+    SCHEMA_VERSION = 1
+    SUPPORTED_SCHEMA_VERSIONS = [SCHEMA_VERSION].freeze #: Array[Integer]
 
-    # @rbs (untyped value) -> untyped
+    # @rbs (Object? value) -> Object?
     def deep_freeze(value)
       case value
       when Array then value.each { |item| deep_freeze(item) }
@@ -52,13 +57,13 @@ module Ibex
       # @rbs () -> bool
       def nonterminal? = @kind == :nonterminal
 
-      # @rbs (?schema_version: Integer) -> Hash[Symbol, untyped]
-      def to_h(schema_version: SCHEMA_VERSION)
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
         value = { id: @id, name: @name, kind: @kind, reserved: @reserved,
-                  prec: @precedence, loc: @location } #: Hash[Symbol, untyped]
+                  prec: @precedence, loc: @location } #: Hash[Symbol, Object?]
         value[:display_name] = @display_name if @display_name
         value[:semantic_type] = @semantic_type if @semantic_type
-        value[:doc] = @documentation if schema_version >= 2
+        value[:doc] = @documentation
         value
       end
     end
@@ -82,11 +87,11 @@ module Ibex
         freeze
       end
 
-      # @rbs (?schema_version: Integer) -> Hash[Symbol, untyped]
-      def to_h(schema_version: SCHEMA_VERSION)
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
         value = { code: @code, loc: @location, named_refs: @named_refs,
-                  context_length: @context_length } #: Hash[Symbol, untyped]
-        value[:composition] = @composition if schema_version >= 2
+                  context_length: @context_length } #: Hash[Symbol, Object?]
+        value[:composition] = @composition
         value
       end
     end
@@ -98,13 +103,13 @@ module Ibex
       attr_reader :rhs #: Array[Integer]
       attr_reader :action #: Action?
       attr_reader :precedence_override #: Integer?
-      attr_reader :origin #: Hash[Symbol, untyped]
+      attr_reader :origin #: Hash[Symbol, Object?]
       attr_reader :documentation #: String?
       attr_reader :expansion #: production_expansion?
       attr_reader :node #: node_annotation?
 
       # @rbs (id: Integer, lhs: Integer, rhs: Array[Integer], action: Action?, precedence_override: Integer?,
-      #   origin: Hash[Symbol, untyped], ?documentation: String?, ?expansion: production_expansion?,
+      #   origin: Hash[Symbol, Object?], ?documentation: String?, ?expansion: production_expansion?,
       #   ?node: node_annotation?) -> void
       def initialize(id:, lhs:, rhs:, action:, precedence_override:, origin:, documentation: nil, expansion: nil,
                      node: nil)
@@ -120,15 +125,13 @@ module Ibex
         freeze
       end
 
-      # @rbs (?schema_version: Integer) -> Hash[Symbol, untyped]
-      def to_h(schema_version: SCHEMA_VERSION)
-        value = { id: @id, lhs: @lhs, rhs: @rhs, action: @action&.to_h(schema_version: schema_version),
-                  prec_override: @precedence_override, origin: @origin } #: Hash[Symbol, untyped]
-        if schema_version >= 2
-          value[:doc] = @documentation
-          value[:expansion] = @expansion
-          value[:node] = @node if @node
-        end
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
+        value = { id: @id, lhs: @lhs, rhs: @rhs, action: @action&.to_h,
+                  prec_override: @precedence_override, origin: @origin } #: Hash[Symbol, Object?]
+        value[:doc] = @documentation
+        value[:expansion] = @expansion
+        value[:node] = @node if @node
         value
       end
     end
@@ -145,7 +148,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         { code: @code, loc: @location }
       end
@@ -174,25 +177,47 @@ module Ibex
       attr_reader :warnings #: Array[grammar_warning]
       attr_reader :schema_version #: Integer
       attr_reader :source_provenance #: source_provenance?
-      attr_reader :migration #: migration_metadata?
+      attr_reader :parser_contract #: ParserContract
 
       # @rbs (class_name: String, superclass: String?, start: String, expect: Integer, ?expect_rr: Integer?,
       #   options: grammar_options,
       #   symbols: Array[GrammarSymbol], productions: Array[Production], user_code: Hash[String, String],
       #   conversions: Hash[String, String], warnings: Array[grammar_warning], ?user_code_chunks: user_code_chunks?,
-      #   ?schema_version: Integer, ?source_provenance: source_provenance?,
-      #   ?migration: migration_metadata?, ?parser_parameters: Array[parser_parameter],
+      #   ?parser_parameters: Array[parser_parameter],
       #   ?value_printers: Array[value_printer], ?grammar_tests: Array[grammar_test],
       #   ?recovery: recovery_policy?, ?lexer: Lexer?,
-      #   ?mode: grammar_mode, ?starts: Array[String]?) -> void
+      #   ?mode: grammar_mode, ?starts: Array[String]?, ?parser_contract: ParserContract,
+      #   ?source_provenance: source_provenance?) -> void
       # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
-      # Immutable versioned IR is constructed from explicit public fields.
+      # Immutable current IR is constructed from explicit public fields.
       def initialize(class_name:, superclass:, start:, expect:, options:, symbols:, productions:, user_code:,
-                     conversions:, warnings:, user_code_chunks: nil, schema_version: SCHEMA_VERSION,
-                     source_provenance: nil, migration: nil, expect_rr: nil, parser_parameters: [], value_printers: [],
-                     grammar_tests: [], recovery: nil, lexer: nil, mode: :default, starts: nil)
+                     conversions:, warnings:, user_code_chunks: nil,
+                     source_provenance: nil, expect_rr: nil, parser_parameters: [], value_printers: [],
+                     grammar_tests: [], recovery: nil, lexer: nil, mode: :default, starts: nil,
+                     parser_contract: ParserContract.new)
+        initialize_current(
+          class_name: class_name, superclass: superclass, start: start, expect: expect, options: options,
+          symbols: symbols, productions: productions, user_code: user_code, conversions: conversions,
+          warnings: warnings, user_code_chunks: user_code_chunks,
+          source_provenance: source_provenance, expect_rr: expect_rr,
+          parser_parameters: parser_parameters, value_printers: value_printers, grammar_tests: grammar_tests,
+          recovery: recovery, lexer: lexer, mode: mode, starts: starts, parser_contract: parser_contract
+        )
+      end
+
+      # @rbs (class_name: String, superclass: String?, start: String, expect: Integer, options: grammar_options,
+      #   symbols: Array[GrammarSymbol], productions: Array[Production], user_code: Hash[String, String],
+      #   conversions: Hash[String, String], warnings: Array[grammar_warning], user_code_chunks: user_code_chunks?,
+      #   source_provenance: source_provenance?, expect_rr: Integer?, parser_parameters: Array[parser_parameter],
+      #   value_printers: Array[value_printer], grammar_tests: Array[grammar_test], recovery: recovery_policy?,
+      #   lexer: Lexer?, mode: grammar_mode, starts: Array[String]?, parser_contract: ParserContract) -> void
+      def initialize_current(class_name:, superclass:, start:, expect:, options:, symbols:, productions:, user_code:,
+                             conversions:, warnings:, user_code_chunks:, source_provenance:, expect_rr:,
+                             parser_parameters:, value_printers:, grammar_tests:, recovery:, lexer:, mode:, starts:,
+                             parser_contract:)
         validate_mode(mode)
         normalized_starts = validate_starts(start, starts, mode)
+        validate_current_metadata(parser_contract)
 
         @class_name = class_name.freeze
         @superclass = superclass&.freeze
@@ -214,14 +239,15 @@ module Ibex
         validate_user_code_chunks
         @conversions = IR.deep_freeze(conversions)
         @warnings = IR.deep_freeze(warnings)
-        @schema_version = schema_version
+        @schema_version = SCHEMA_VERSION
         @source_provenance = IR.deep_freeze(source_provenance)
-        @migration = IR.deep_freeze(migration)
+        @parser_contract = IR.deep_freeze(parser_contract)
         @symbols_by_name = @symbols.to_h { |symbol| [symbol.name, symbol] }.freeze
         @symbols_by_id = @symbols.to_h { |symbol| [symbol.id, symbol] }.freeze
         freeze
       end
       # rubocop:enable Metrics/AbcSize, Metrics/ParameterLists
+      private :initialize_current
 
       # @rbs (String name) -> GrammarSymbol?
       def symbol(name) = @symbols_by_name[name]
@@ -232,14 +258,14 @@ module Ibex
       # @rbs () -> Array[GrammarSymbol]
       def nonterminals = @symbols.select(&:nonterminal?)
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         value = { ibex_ir: "grammar", schema_version: @schema_version, class_name: @class_name, superclass: @superclass,
                   start: @start, expect: @expect, options: @options,
-                  symbols: @symbols.map { |symbol| symbol.to_h(schema_version: @schema_version) },
-                  productions: @productions.map { |production| production.to_h(schema_version: @schema_version) },
+                  symbols: @symbols.map(&:to_h),
+                  productions: @productions.map(&:to_h),
                   user_code: @user_code, conversions: @conversions,
-                  warnings: @warnings } #: Hash[Symbol, untyped]
+                  warnings: @warnings } #: Hash[Symbol, Object?]
         append_optional_metadata(value)
         value
       end
@@ -262,30 +288,28 @@ module Ibex
         values
       end
 
-      # @rbs (Hash[Symbol, untyped] value) -> void
+      # @rbs (Hash[Symbol, Object?] value) -> void
       def append_optional_metadata(value)
         append_parser_metadata(value)
         append_recovery_metadata(value)
         value[:user_code_chunks] = @user_code_chunks.transform_values { |chunks| chunks.map(&:to_h) } \
           unless @user_code_chunks.empty?
-        return unless @schema_version >= 2
-
         value[:source_provenance] = @source_provenance
-        value[:migration] = @migration
+        value[:parser_contract] = @parser_contract.to_h
       end
 
-      # @rbs (Hash[Symbol, untyped] value) -> void
+      # @rbs (Hash[Symbol, Object?] value) -> void
       def append_parser_metadata(value)
         value[:expect_rr] = @expect_rr unless @expect_rr.nil?
         value[:mode] = @mode if @mode == :extended
         value[:starts] = @starts if @starts.length > 1
         value[:params] = @parser_parameters unless @parser_parameters.empty?
         value[:printers] = @value_printers unless @value_printers.empty?
-        value[:tests] = @grammar_tests unless @grammar_tests.empty? || @schema_version < 2
-        value[:lexer] = @lexer.to_h if @lexer && @schema_version >= 2
+        value[:tests] = @grammar_tests unless @grammar_tests.empty?
+        value[:lexer] = @lexer.to_h if @lexer
       end
 
-      # @rbs (Hash[Symbol, untyped] value) -> void
+      # @rbs (Hash[Symbol, Object?] value) -> void
       def append_recovery_metadata(value)
         return if @recovery[:sync_tokens].empty? && @recovery[:on_error_reduce].empty?
 
@@ -300,6 +324,13 @@ module Ibex
           raise Ibex::Error, "(ir):1:1: user-code chunks do not match the concatenated #{name} section"
         end
       end
+
+      # @rbs (ParserContract parser_contract) -> void
+      def validate_current_metadata(parser_contract)
+        return if parser_contract.is_a?(ParserContract)
+
+        raise ArgumentError, "parser_contract must be a ParserContract"
+      end
     end
   end
 end

data/lib/ibex/ir/lexer_ir.rb

@@ -32,7 +32,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, lexer_rule_document_value]
       def to_h
         {
           id: @id, state: @state, kind: @kind, token: @token, pattern: @pattern,
@@ -41,15 +41,15 @@ module Ibex
       end
     end
 
-    # Independently versioned lexer contract embedded by Grammar IR v2.
+    # Independently versioned lexer contract embedded by the current Grammar IR.
     class Lexer
       attr_reader :states #: Array[String]
       attr_reader :rules #: Array[LexerRule]
-      attr_reader :warnings #: Array[Hash[Symbol, untyped]]
+      attr_reader :warnings #: Array[lexer_warning]
       attr_reader :schema_version #: Integer
       attr_reader :source_provenance #: source_provenance?
 
-      # @rbs (states: Array[String], rules: Array[LexerRule], warnings: Array[Hash[Symbol, untyped]],
+      # @rbs (states: Array[String], rules: Array[LexerRule], warnings: Array[lexer_warning],
       #   ?schema_version: Integer, ?source_provenance: source_provenance?) -> void
       def initialize(states:, rules:, warnings:, schema_version: LEXER_SCHEMA_VERSION, source_provenance: nil)
         raise ArgumentError, "lexer states must start with INITIAL" unless states.first == "INITIAL"
@@ -63,7 +63,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, lexer_document_value]
       def to_h
         {
           ibex_ir: "lexer", schema_version: @schema_version, initial_state: "INITIAL",

data/lib/ibex/ir/parser_contract.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "../location"
+
+module Ibex
+  module IR
+    # Root-owned parser configuration persisted by the current Grammar IR.
+    class ParserContract
+      # @rbs!
+      #   type definition = { configuration: String, values: Array[Symbol] }
+      #   type entry_location = { file: String?, line: Integer, column: Integer }
+      #   type entry_value = String? | bool | entry_location?
+
+      DEFINITIONS = {
+        algorithm: {
+          configuration: "parser.algorithm", values: %i[slr lalr ielr lr1].freeze
+        }.freeze,
+        entries: {
+          configuration: "parser.entries", values: %i[shared isolated].freeze
+        }.freeze,
+        cst_trivia: {
+          configuration: "cst.trivia", values: %i[leading balanced drop].freeze
+        }.freeze
+      }.freeze #: Hash[Symbol, definition]
+
+      # One specified or explicitly unspecified contract field.
+      class Entry
+        attr_reader :key #: Symbol
+        attr_reader :value #: Symbol?
+        attr_reader :location #: Location?
+        attr_reader :explicit #: bool
+
+        # @rbs (Symbol key, ?value: Symbol?, ?location: Location?, ?explicit: bool) -> void
+        def initialize(key, value: nil, location: nil, explicit: false)
+          definition = DEFINITIONS.fetch(key) { raise ArgumentError, "unknown parser contract key #{key.inspect}" }
+          validate_state!(key, definition.fetch(:values), value, location, explicit)
+
+          @key = key
+          @value = value
+          @location = location
+          @explicit = explicit
+          freeze
+        end
+
+        # @rbs () -> Hash[Symbol, entry_value]
+        def to_h
+          { value: @value&.to_s, explicit: @explicit, loc: serialized_location }
+        end
+
+        private
+
+        # @rbs (Symbol key, Array[Symbol] allowed, Symbol? value, Location? location, bool explicit) -> void
+        def validate_state!(key, allowed, value, location, explicit)
+          raise ArgumentError, "explicit must be boolean" unless [true, false].include?(explicit)
+
+          if explicit
+            raise ArgumentError, "#{key} must be one of #{allowed.join(', ')}" unless allowed.include?(value)
+            unless location.is_a?(Location) && location.file && !location.file.empty?
+              raise ArgumentError, "explicit #{key} requires a source location with a file"
+            end
+
+            return
+          end
+
+          raise ArgumentError, "unspecified #{key} cannot carry a value" unless value.nil?
+          raise ArgumentError, "unspecified #{key} cannot carry a source location" unless location.nil?
+        end
+
+        # @rbs () -> entry_location?
+        def serialized_location
+          location = @location
+          return unless location
+
+          { file: location.file, line: location.line, column: location.column }
+        end
+      end
+
+      attr_reader :algorithm #: Entry
+      attr_reader :entries #: Entry
+      attr_reader :cst_trivia #: Entry
+
+      # @rbs (?algorithm: Entry?, ?entries: Entry?, ?cst_trivia: Entry?) -> void
+      def initialize(algorithm: nil, entries: nil, cst_trivia: nil)
+        @algorithm = normalize_entry(:algorithm, algorithm)
+        @entries = normalize_entry(:entries, entries)
+        @cst_trivia = normalize_entry(:cst_trivia, cst_trivia)
+        freeze
+      end
+
+      # @rbs () -> Hash[Symbol, Hash[Symbol, entry_value]]
+      def to_h
+        {
+          algorithm: @algorithm.to_h,
+          entries: @entries.to_h,
+          cst_trivia: @cst_trivia.to_h
+        }
+      end
+
+      # Values supplied to the typed resolver; unspecified fields are absent.
+      # @rbs () -> Hash[String, Symbol]
+      def configuration_values
+        specified_entries.to_h do |entry|
+          value = entry.value || raise("explicit parser contract entry is missing its value")
+          [DEFINITIONS.fetch(entry.key).fetch(:configuration), value]
+        end
+      end
+
+      # Source locations supplied to the typed resolver.
+      # @rbs () -> Hash[String, Location]
+      def configuration_locations
+        specified_entries.to_h do |entry|
+          location = entry.location || raise("explicit parser contract entry is missing its location")
+          [DEFINITIONS.fetch(entry.key).fetch(:configuration), location]
+        end
+      end
+
+      private
+
+      # @rbs (Symbol key, Entry? entry) -> Entry
+      def normalize_entry(key, entry)
+        entry ||= Entry.new(key)
+        raise ArgumentError, "#{key} must be a ParserContract::Entry" unless entry.is_a?(Entry)
+        raise ArgumentError, "#{key} entry has key #{entry.key.inspect}" unless entry.key == key
+
+        entry
+      end
+
+      # @rbs () -> Array[Entry]
+      def specified_entries
+        [@algorithm, @entries, @cst_trivia].select(&:explicit)
+      end
+    end
+  end
+end