ibex 0.1.0 → 0.3.0

data/lib/ibex/grammar_tests.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "json"
+require "rbconfig"
+require "tempfile"
+require "timeout"
+require "tmpdir"
+
+module Ibex
+  # Executes grammar-declared source examples against one generated parser.
+  module GrammarTests
+    DEFAULT_TIMEOUT = 10
+    RESULT_MARKER = "IBEX_GRAMMAR_TEST_RESULT="
+
+    Result = Struct.new(
+      :expectation, #: Symbol
+      :actual, #: Symbol
+      :error_class, #: String?
+      :error_message, #: String?
+      :location, #: IR::location
+      :production_ids, #: Array[Integer]
+      keyword_init: true
+    )
+
+    class Result
+      # @rbs () -> bool
+      def passed? = expectation == actual
+    end
+
+    ProductionCoverage = Struct.new(
+      :covered_ids, #: Array[Integer]
+      :missing_ids, #: Array[Integer]
+      :production_count, #: Integer
+      keyword_init: true
+    )
+
+    class ProductionCoverage
+      # @rbs () -> Float
+      def percentage
+        return 100.0 if production_count.zero?
+
+        covered_ids.length.fdiv(production_count) * 100
+      end
+
+      # @rbs (Integer minimum) -> bool
+      def meets?(minimum)
+        covered_ids.length * 100 >= production_count * minimum
+      end
+
+      # @rbs () -> bool
+      def complete? = missing_ids.empty?
+    end
+
+    # Runs all examples in one isolated process while creating a fresh parser
+    # instance for every case.
+    class Runner
+      CHILD_RUNNER = <<~'RUBY'
+        require "json"
+
+        load ARGV.fetch(0)
+        parser_class = ARGV.fetch(1).split("::").reject(&:empty?).reduce(Object) do |scope, name|
+          scope.const_get(name, false)
+        end
+        tests = JSON.parse(ARGV.fetch(2))
+        results = tests.map do |test|
+          production_ids = []
+          begin
+            parser = parser_class.new
+            raise NoMethodError, "#{parser_class} must define parse(source)" unless parser.respond_to?(:parse)
+
+            parser.observe do |event|
+              production_ids << event.data.fetch("production_id") if event.type == :reduce
+            end
+            parser.parse(test.fetch("source"))
+            result = { "actual" => "accept", "error_class" => nil, "error_message" => nil }
+          rescue Ibex::Runtime::ParseError => error
+            result = { "actual" => "reject", "error_class" => error.class.name, "error_message" => error.message }
+          rescue SystemExit, SignalException, StandardError => error
+            result = { "actual" => "error", "error_class" => error.class.name, "error_message" => error.message }
+          end
+          result.merge("production_ids" => production_ids)
+        end
+        puts "IBEX_GRAMMAR_TEST_RESULT=#{JSON.generate(results)}"
+      RUBY
+
+      # @rbs @automaton: IR::Automaton
+      # @rbs @timeout: Integer
+
+      # @rbs (IR::Automaton automaton, ?timeout: Integer) -> void
+      def initialize(automaton, timeout: DEFAULT_TIMEOUT)
+        raise ArgumentError, "timeout must be a positive Integer" unless timeout.is_a?(Integer) && timeout.positive?
+
+        @automaton = automaton
+        @timeout = timeout
+      end
+
+      # @rbs () -> Array[Result]
+      def run
+        grammar = @automaton.grammar
+        raise Ibex::Error, "(test):1:1: grammar declares no %test cases" if grammar.grammar_tests.empty?
+        unless grammar.parser_parameters.empty?
+          raise Ibex::Error, "(test):1:1: %test cannot instantiate a parser with required %param declarations"
+        end
+
+        Dir.mktmpdir("ibex-grammar-tests") do |directory|
+          parser_path = File.join(directory, "parser.rb")
+          runner_path = File.join(directory, "runner.rb")
+          File.binwrite(parser_path, generated_parser)
+          File.binwrite(runner_path, CHILD_RUNNER)
+          execute_child(parser_path, runner_path)
+        end
+      end
+
+      # @rbs (Array[Result] results) -> ProductionCoverage
+      def production_coverage(results)
+        production_count = @automaton.grammar.productions.length
+        covered_ids = results.flat_map(&:production_ids).uniq.sort.freeze
+        missing_ids = ((0...production_count).to_a - covered_ids).freeze
+        ProductionCoverage.new(
+          covered_ids: covered_ids, missing_ids: missing_ids, production_count: production_count
+        ).freeze
+      end
+
+      private
+
+      # @rbs () -> String
+      def generated_parser
+        Codegen::Ruby.new(@automaton, table: :compact, embedded: true, line_convert: true).generate
+      end
+
+      # @rbs (String parser_path, String runner_path) -> Array[Result]
+      def execute_child(parser_path, runner_path)
+        payload = JSON.generate(@automaton.grammar.grammar_tests)
+        stdout = Tempfile.new("ibex-grammar-test-stdout")
+        stderr = Tempfile.new("ibex-grammar-test-stderr")
+        stdout_path = stdout.path || raise(Ibex::Error, "(test):1:1: missing temporary stdout path")
+        stderr_path = stderr.path || raise(Ibex::Error, "(test):1:1: missing temporary stderr path")
+        pid = spawn(
+          RbConfig.ruby, runner_path, parser_path, @automaton.grammar.class_name, payload,
+          out: stdout_path, err: stderr_path
+        )
+        status = wait_for_child(pid)
+        output = File.binread(stdout_path)
+        errors = File.binread(stderr_path)
+        raise_child_failure(status, errors) unless status.success?
+
+        decode_results(output)
+      ensure
+        stdout&.close!
+        stderr&.close!
+      end
+
+      # @rbs (Integer pid) -> Process::Status
+      def wait_for_child(pid)
+        Timeout.timeout(@timeout) { Process.wait2(pid).fetch(1) }
+      rescue Timeout::Error
+        Process.kill("KILL", pid)
+        Process.wait(pid)
+        raise Ibex::Error, "(test):1:1: grammar tests exceeded #{@timeout} seconds"
+      end
+
+      # @rbs (Process::Status status, String errors) -> bot
+      def raise_child_failure(status, errors)
+        detail = errors.lines.last&.strip
+        suffix = detail && !detail.empty? ? ": #{detail}" : ""
+        raise Ibex::Error, "(test):1:1: grammar test process exited with status #{status.exitstatus}#{suffix}"
+      end
+
+      # @rbs (String output) -> Array[Result]
+      def decode_results(output)
+        line = output.lines.reverse.find { |candidate| candidate.start_with?(RESULT_MARKER) }
+        raise Ibex::Error, "(test):1:1: grammar test process produced no result" unless line
+
+        documents = JSON.parse(line.delete_prefix(RESULT_MARKER).strip)
+        tests = @automaton.grammar.grammar_tests
+        unless documents.is_a?(Array) && documents.length == tests.length
+          raise Ibex::Error, "(test):1:1: grammar test process returned an invalid result count"
+        end
+
+        tests.zip(documents).map { |test, document| build_result(test, document) }
+      rescue JSON::ParserError, ArgumentError => e
+        raise Ibex::Error, "(test):1:1: invalid grammar test process result: #{e.message}"
+      end
+
+      # @rbs (IR::grammar_test test, Object? document) -> Result
+      def build_result(test, document)
+        unless document.is_a?(Hash) && %w[accept reject error].include?(document["actual"])
+          raise Ibex::Error, "(test):1:1: grammar test process returned an invalid case result"
+        end
+
+        production_ids = document["production_ids"]
+        production_count = @automaton.grammar.productions.length
+        unless production_ids.is_a?(Array) &&
+               production_ids.all? { |id| id.is_a?(Integer) && id.between?(0, production_count - 1) }
+          raise Ibex::Error, "(test):1:1: grammar test process returned invalid production coverage"
+        end
+
+        Result.new(
+          expectation: test[:expectation], actual: document.fetch("actual").to_sym,
+          error_class: document["error_class"], error_message: document["error_message"],
+          location: test[:loc], production_ids: production_ids.freeze
+        ).freeze
+      end
+    end
+  end
+end

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}")
@@ -74,36 +74,111 @@ module Ibex
       attr_reader :grammar_digest #: String
       attr_reader :grammar #: Grammar
       attr_reader :states #: Array[AutomatonState]
+      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) -> 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, 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
+
+      # @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
-        { 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 }
+        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, Object?]
+        value[:entry_states] = @entry_states unless @entry_states == { @grammar.start => 0 }
+        value[:entry_construction] = @entry_construction
+        value
       end
 
       private
 
+      # @rbs () -> void
+      def validate_entry_states
+        ordered = @grammar.starts.select { |name| @entry_states.key?(name) }
+        unless @entry_states.any? && @entry_states.keys == ordered
+          raise Ibex::Error, "(ir):1:1: automaton entry states must be an ordered subset of grammar starts"
+        end
+
+        @entry_states.each do |name, state|
+          next if state.between?(0, @states.length - 1)
+
+          raise Ibex::Error, "(ir):1:1: entry #{name} references missing state #{state}"
+        end
+      end
+
       # @rbs (Grammar grammar) -> String
       def digest_for(grammar)
         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,10 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "parser_contract"
+
 module Ibex
   module IR
+    # 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) }
@@ -26,16 +32,23 @@ module Ibex
       attr_reader :reserved #: bool
       attr_reader :precedence #: precedence?
       attr_reader :location #: location?
+      attr_reader :display_name #: String?
+      attr_reader :semantic_type #: String?
+      attr_reader :documentation #: String?
 
       # @rbs (id: Integer, name: String, kind: Symbol, ?reserved: bool, ?precedence: precedence?,
-      #   ?location: location?) -> void
-      def initialize(id:, name:, kind:, reserved: false, precedence: nil, location: nil)
+      #   ?location: location?, ?display_name: String?, ?semantic_type: String?, ?documentation: String?) -> void
+      def initialize(id:, name:, kind:, reserved: false, precedence: nil, location: nil, display_name: nil,
+                     semantic_type: nil, documentation: nil)
         @id = id
         @name = name.freeze
         @kind = kind.to_sym
         @reserved = reserved
         @precedence = IR.deep_freeze(precedence)
         @location = IR.deep_freeze(location)
+        @display_name = display_name&.freeze
+        @semantic_type = semantic_type&.freeze
+        @documentation = documentation&.freeze
         freeze
       end
 
@@ -44,9 +57,14 @@ module Ibex
       # @rbs () -> bool
       def nonterminal? = @kind == :nonterminal
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
-        { id: @id, name: @name, kind: @kind, reserved: @reserved, prec: @precedence, loc: @location }
+        value = { id: @id, name: @name, kind: @kind, reserved: @reserved,
+                  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
+        value
       end
     end
 
@@ -56,19 +74,25 @@ module Ibex
       attr_reader :location #: location
       attr_reader :named_refs #: Array[named_ref]
       attr_reader :context_length #: Integer
+      attr_reader :composition #: action_composition?
 
-      # @rbs (code: String, location: location, ?named_refs: Array[named_ref], ?context_length: Integer) -> void
-      def initialize(code:, location:, named_refs: [], context_length: 0)
+      # @rbs (code: String, location: location, ?named_refs: Array[named_ref], ?context_length: Integer,
+      #   ?composition: action_composition?) -> void
+      def initialize(code:, location:, named_refs: [], context_length: 0, composition: nil)
         @code = code.freeze
         @location = IR.deep_freeze(location)
         @named_refs = IR.deep_freeze(named_refs)
         @context_length = context_length
+        @composition = IR.deep_freeze(composition)
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
-        { code: @code, loc: @location, named_refs: @named_refs, context_length: @context_length }
+        value = { code: @code, loc: @location, named_refs: @named_refs,
+                  context_length: @context_length } #: Hash[Symbol, Object?]
+        value[:composition] = @composition
+        value
       end
     end
 
@@ -79,24 +103,36 @@ 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]) -> void
-      def initialize(id:, lhs:, rhs:, action:, precedence_override:, origin:)
+      #   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)
         @id = id
         @lhs = lhs
         @rhs = rhs.freeze
         @action = action
         @precedence_override = precedence_override
         @origin = IR.deep_freeze(origin)
+        @documentation = documentation&.freeze
+        @expansion = IR.deep_freeze(expansion)
+        @node = IR.deep_freeze(node)
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
-        { id: @id, lhs: @lhs, rhs: @rhs, action: @action&.to_h, prec_override: @precedence_override,
-          origin: @origin }
+        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
 
@@ -112,7 +148,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         { code: @code, loc: @location }
       end
@@ -123,7 +159,15 @@ module Ibex
       attr_reader :class_name #: String
       attr_reader :superclass #: String?
       attr_reader :start #: String
+      attr_reader :starts #: Array[String]
+      attr_reader :mode #: grammar_mode
       attr_reader :expect #: Integer
+      attr_reader :expect_rr #: Integer?
+      attr_reader :parser_parameters #: Array[parser_parameter]
+      attr_reader :value_printers #: Array[value_printer]
+      attr_reader :grammar_tests #: Array[grammar_test]
+      attr_reader :lexer #: Lexer?
+      attr_reader :recovery #: recovery_policy
       attr_reader :options #: grammar_options
       attr_reader :symbols #: Array[GrammarSymbol]
       attr_reader :productions #: Array[Production]
@@ -132,17 +176,61 @@ module Ibex
       attr_reader :conversions #: Hash[String, String]
       attr_reader :warnings #: Array[grammar_warning]
       attr_reader :schema_version #: Integer
+      attr_reader :source_provenance #: source_provenance?
+      attr_reader :parser_contract #: ParserContract
 
-      # @rbs (class_name: String, superclass: String?, start: String, expect: Integer, options: grammar_options,
+      # @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) -> void
+      #   ?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,
+      #   ?source_provenance: source_provenance?) -> void
+      # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
+      # 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)
+                     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
         @start = start.freeze
+        @starts = normalized_starts.map(&:freeze).freeze
+        @mode = mode
         @expect = expect
+        @expect_rr = expect_rr
+        @parser_parameters = IR.deep_freeze(parser_parameters)
+        @value_printers = IR.deep_freeze(value_printers)
+        @grammar_tests = IR.deep_freeze(grammar_tests)
+        @lexer = lexer
+        @recovery = IR.deep_freeze(recovery || { sync_tokens: [], on_error_reduce: [] })
         @options = IR.deep_freeze(options)
         @symbols = symbols.freeze
         @productions = productions.freeze
@@ -151,11 +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)
+        @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]
@@ -166,19 +258,64 @@ 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(&:to_h),
-                  productions: @productions.map(&:to_h), user_code: @user_code, conversions: @conversions,
-                  warnings: @warnings } #: Hash[Symbol, untyped]
-        value[:user_code_chunks] = @user_code_chunks.transform_values { |chunks| chunks.map(&:to_h) } \
-          unless @user_code_chunks.empty?
+                  start: @start, expect: @expect, options: @options,
+                  symbols: @symbols.map(&:to_h),
+                  productions: @productions.map(&:to_h),
+                  user_code: @user_code, conversions: @conversions,
+                  warnings: @warnings } #: Hash[Symbol, Object?]
+        append_optional_metadata(value)
         value
       end
 
       private
 
+      # @rbs (grammar_mode mode) -> void
+      def validate_mode(mode)
+        raise ArgumentError, "mode must be :default or :extended" unless %i[default extended].include?(mode)
+      end
+
+      # @rbs (String start, Array[String]? starts, grammar_mode mode) -> Array[String]
+      def validate_starts(start, starts, mode)
+        values = starts || [start]
+        raise ArgumentError, "starts must contain the primary start symbol" if values.empty?
+        raise ArgumentError, "start must be the first entry in starts" unless values.first == start
+        raise ArgumentError, "starts must be unique" unless values.uniq.length == values.length
+        raise ArgumentError, "multiple start symbols require extended mode" if values.length > 1 && mode != :extended
+
+        values
+      end
+
+      # @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?
+        value[:source_provenance] = @source_provenance
+        value[:parser_contract] = @parser_contract.to_h
+      end
+
+      # @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?
+        value[:lexer] = @lexer.to_h if @lexer
+      end
+
+      # @rbs (Hash[Symbol, Object?] value) -> void
+      def append_recovery_metadata(value)
+        return if @recovery[:sync_tokens].empty? && @recovery[:on_error_reduce].empty?
+
+        value[:recovery] = @recovery
+      end
+
       # @rbs () -> void
       def validate_user_code_chunks
         @user_code_chunks.each do |name, chunks|
@@ -187,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