ibex 0.1.0 → 0.3.0

data/lib/ibex/normalize.rb

@@ -1,21 +1,56 @@
 # frozen_string_literal: true
 
 require_relative "normalize/declarations"
+require_relative "normalize/parser_configuration"
+require_relative "normalize/grammar_builder"
+require_relative "normalize/lexer"
+require_relative "normalize/recovery_declarations"
 require_relative "normalize/expression"
+require_relative "normalize/parameter_validation"
+require_relative "normalize/inline_validation"
+require_relative "normalize/parameter_substitution"
+require_relative "normalize/parameter_ebnf_lowering"
+require_relative "normalize/parameter_lowering"
+require_relative "normalize/parameters"
+require_relative "normalize/named_references"
+require_relative "normalize/nodes"
 require_relative "normalize/expander"
+require_relative "normalize/inline_expansion"
 require_relative "normalize/diagnostics"
+require_relative "frontend/resolution"
 
 module Ibex
   # Converts a frontend AST into immutable Grammar IR.
   class Normalizer
     include NormalizeDeclarations
+    include NormalizeParserConfiguration
+    include NormalizeGrammarBuilder
+    include NormalizeLexer
+    include NormalizeRecoveryDeclarations
+    include NormalizeParameterValidation
+    include NormalizeInlineValidation
+    include NormalizeParameterSubstitution
+    include NormalizeParameterEbnfLowering
+    include NormalizeParameterLowering
+    include NormalizeParameters
+    include NormalizeNamedReferences
+    include NormalizeNodes
     include NormalizeExpander
+    include NormalizeInlineExpansion
     include NormalizeDiagnostics
 
     RESERVED_NAMES = %w[result val _values].freeze #: Array[String]
+    RUBY_KEYWORDS = %w[
+      __ENCODING__ __FILE__ __LINE__ alias and begin break case class def defined do else elsif end ensure false for if
+      in module next nil not or redo rescue retry return self super then true undef unless until when while yield
+    ].freeze #: Array[String]
+    DEFAULT_MAX_PARAMETER_SPECIALIZATIONS = 1_000
+    DEFAULT_MAX_INLINE_EXPANSIONS = 10_000
 
     # @rbs @ast: Frontend::AST::Root
-    # @rbs @mode: Symbol
+    # @rbs @resolution: Frontend::Resolution?
+    # @rbs @current_include_chain: Array[IR::source_provenance]
+    # @rbs @mode: IR::grammar_mode
     # @rbs @symbols: Array[IR::GrammarSymbol]
     # @rbs @symbols_by_name: Hash[String, IR::GrammarSymbol]
     # @rbs @productions: Array[IR::Production]
@@ -24,40 +59,101 @@ module Ibex
     # @rbs @declared_tokens: Hash[String, IR::location]
     # @rbs @precedence: Hash[String, IR::precedence]
     # @rbs @precedence_locations: Hash[String, IR::location]
+    # @rbs @display_names: Hash[String, String]
+    # @rbs @display_name_locations: Hash[String, IR::location]
+    # @rbs @semantic_types: Hash[String, String]
+    # @rbs @semantic_type_locations: Hash[String, IR::location]
     # @rbs @options: IR::grammar_options
     # @rbs @expected_conflicts: Integer
+    # @rbs @expected_rr_conflicts: Integer?
     # @rbs @conversions: Hash[String, String]
-    # @rbs @explicit_start: String?
+    # @rbs @parser_parameters: Array[IR::parser_parameter]
+    # @rbs @value_printers: Hash[String, IR::value_printer]
+    # @rbs @recovery_sync_tokens: Array[String]
+    # @rbs @on_error_reduce_groups: Array[Array[String]]
+    # @rbs @grammar_tests: Array[IR::grammar_test]
+    # @rbs @lexer_declaration: Frontend::AST::Lexer?
+    # @rbs @parser_configuration: Frontend::AST::ParserConfiguration?
+    # @rbs @explicit_starts: Array[String]?
+    # @rbs @start_names: Array[String]
     # @rbs @start_name: String
     # @rbs @start_location: Frontend::Location?
+    # @rbs @parameter_templates: Hash[String, Array[Frontend::AST::Rule]]
+    # @rbs @parameter_formals: Hash[String, Array[String]]
+    # @rbs @parameter_specializations: Hash[[String, Array[String]], String]
+    # @rbs @parameter_worklist: Array[NormalizeParameters::parameter_frame]
+    # @rbs @parameter_worklist_active: bool
+    # @rbs @max_parameter_specializations: Integer
+    # @rbs @current_parameter_expansion: IR::parameter_expansion?
+    # @rbs @rule_documentation: Hash[String, String]
+    # @rbs @inline_rule_names: Set[String]
+    # @rbs @inline_symbol_ids: Set[Integer]
+    # @rbs @inline_rule_by_symbol: Hash[Integer, String]
+    # @rbs @max_inline_expansions: Integer
+    # @rbs @inline_expansion_count: Integer
+    # @rbs @node_shapes: Hash[String, Array[String]]
+
+    # @rbs (Frontend::AST::Root | Frontend::AST::Fragment | Frontend::Resolution input,
+    #   ?mode: Symbol | String, ?max_parameter_specializations: Integer,
+    #   ?max_inline_expansions: Integer) -> void
+    def initialize(input, mode: :default, max_parameter_specializations: DEFAULT_MAX_PARAMETER_SPECIALIZATIONS,
+                   max_inline_expansions: DEFAULT_MAX_INLINE_EXPANSIONS)
+      validate_positive_limit!(:max_parameter_specializations, max_parameter_specializations)
+      validate_positive_limit!(:max_inline_expansions, max_inline_expansions)
+      normalized_mode = mode.to_sym
+      raise ArgumentError, "mode must be :default or :extended" unless %i[default extended].include?(normalized_mode)
+
+      @resolution = input if input.is_a?(Frontend::Resolution)
+      ast = input.is_a?(Frontend::Resolution) ? input.root : input
+      normalized_mode = :extended if ast.is_a?(Frontend::AST::Root) && ast.extended
+      fail_at(ast.loc, "fragments must be resolved before normalization") if ast.is_a?(Frontend::AST::Fragment)
+      unresolved = ast.declarations.find { |declaration| declaration.is_a?(Frontend::AST::Include) }
+      fail_at(unresolved.loc, "includes must be resolved before normalization") if unresolved
 
-    # @rbs (Frontend::AST::Root ast, ?mode: Symbol | String) -> void
-    def initialize(ast, mode: :racc)
       @ast = ast
-      @mode = mode
+      @mode = normalized_mode #: IR::grammar_mode
       @symbols = [] #: Array[IR::GrammarSymbol]
       @symbols_by_name = {} #: Hash[String, IR::GrammarSymbol]
       @productions = [] #: Array[IR::Production]
       @warnings = [] #: Array[IR::grammar_warning]
       @helper_sequence = 0
+      @current_include_chain = [] #: Array[IR::source_provenance]
+      @parameter_specializations = {} #: Hash[[String, Array[String]], String]
+      @parameter_worklist = [] #: Array[NormalizeParameters::parameter_frame]
+      @parameter_worklist_active = false
+      @max_parameter_specializations = max_parameter_specializations
+      @max_inline_expansions = max_inline_expansions
+      @inline_expansion_count = 0
+      @inline_symbol_ids = Set.new #: Set[Integer]
+      @inline_rule_by_symbol = {} #: Hash[Integer, String]
     end
 
     # @rbs () -> IR::Grammar
     def normalize
       read_declarations
+      gather_parameter_templates
+      gather_inline_rules
       intern_reserved_symbols
       intern_declared_terminals
       intern_user_nonterminals
+      parser_contract = normalized_parser_contract
       normalize_user_productions
+      expand_inline_rules
+      validate_value_printers
+      validate_recovery_declarations
       validate_grammar
-      IR::Grammar.new(class_name: @ast.class_name, superclass: @ast.superclass, start: @start_name,
-                      expect: @expected_conflicts, options: @options, symbols: @symbols,
-                      productions: @productions, user_code: normalized_user_code,
-                      conversions: @conversions, warnings: @warnings, user_code_chunks: normalized_user_code_chunks)
+      build_grammar(parser_contract)
     end
 
     private
 
+    # @rbs (Symbol name, Object value) -> void
+    def validate_positive_limit!(name, value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive Integer"
+    end
+
     # @rbs () -> void
     def intern_reserved_symbols
       intern("$eof", :terminal, reserved: true)
@@ -72,16 +168,62 @@ module Ibex
 
     # @rbs () -> void
     def intern_user_nonterminals
-      @ast.rules.each { |rule| intern(rule.lhs, :nonterminal, location: rule.loc.to_h) }
-      @start_name = @explicit_start || @ast.rules.first&.lhs
-      fail_at(@ast.loc, "grammar has no start rule") unless @start_name
-      return if symbol(@start_name)&.nonterminal?
+      @ast.rules.reject { |rule| parameterized_rule?(rule) }.each do |rule|
+        intern_user_nonterminal(rule)
+      end
+      @start_names = normalized_start_names
+      fail_at(@ast.loc, "grammar has no start rule") if @start_names.empty?
+      @start_name = @start_names.fetch(0)
+      @start_names.each do |name|
+        next if symbol(name)&.nonterminal?
 
-      fail_at(@start_location || @ast.loc, "undefined start symbol #{@start_name}")
+        fail_at(@start_location || @ast.loc, "undefined start symbol #{name}")
+      end
     end
 
-    # @rbs (String name, Symbol kind, ?reserved: bool, ?location: IR::location?) -> IR::GrammarSymbol
-    def intern(name, kind, reserved: false, location: nil)
+    # @rbs () -> Array[String]
+    def normalized_start_names
+      explicit = @explicit_starts
+      return explicit if explicit
+
+      candidate = @ast.rules.find { |rule| start_rule_candidate?(rule) }&.lhs
+      candidate ? [candidate] : []
+    end
+
+    # @rbs (Frontend::AST::Rule rule) -> bool
+    def start_rule_candidate?(rule)
+      !parameterized_rule?(rule) && !rule.inline
+    end
+
+    # @rbs (Frontend::AST::Rule rule) -> void
+    def intern_user_nonterminal(rule)
+      definition = intern(
+        rule.lhs, :nonterminal, location: rule.loc.to_h, documentation: @rule_documentation[rule.lhs]
+      )
+      return unless rule.inline
+
+      @inline_symbol_ids << definition.id
+      @inline_rule_by_symbol[definition.id] = rule.lhs
+    end
+
+    # @rbs () -> Hash[String, String]
+    def validated_rule_documentation
+      documentation = {} #: Hash[String, String]
+      @ast.rules.each do |rule|
+        text = rule.documentation
+        next unless text
+
+        existing = documentation[rule.lhs]
+        fail_at(rule.loc, "conflicting documentation for rule #{rule.lhs}") if existing && existing != text
+
+        documentation[rule.lhs] ||= text
+      end
+      documentation
+    end
+
+    # @rbs (String name, Symbol kind, ?reserved: bool, ?location: IR::location?,
+    #   ?documentation: String?, ?metadata_name: String?) -> IR::GrammarSymbol
+    def intern(name, kind, reserved: false, location: nil, documentation: nil, metadata_name: nil)
       existing = symbol(name)
       if existing
         fail_hash(location, "symbol #{name} is both terminal and nonterminal") if existing.kind != kind
@@ -89,8 +231,11 @@ module Ibex
       end
 
       precedence = @precedence[name]
+      metadata_key = metadata_name || name
       definition = IR::GrammarSymbol.new(id: @symbols.length, name: name, kind: kind, reserved: reserved,
-                                         precedence: precedence, location: location)
+                                         precedence: precedence, location: location,
+                                         display_name: @display_names[metadata_key],
+                                         semantic_type: @semantic_types[metadata_key], documentation: documentation)
       @symbols << definition
       @symbols_by_name[name] = definition
       definition
@@ -110,6 +255,9 @@ module Ibex
     def symbol_for_reference(reference)
       existing = symbol(reference.name)
       return existing if existing
+
+      fail_at(reference.loc, "parameterized rule #{reference.name} requires arguments") if
+        parameter_template?(reference.name)
       return undefined_nonterminal(reference) if nonterminal_name?(reference.name)
 
       warn_undeclared_terminal(reference)
@@ -162,5 +310,12 @@ module Ibex
       rendered = location ? "#{location[:file]}:#{location[:line]}:#{location[:column]}" : "(grammar):1:1"
       raise Ibex::Error, "#{rendered}: #{message}"
     end
+
+    # @rbs () -> IR::production_expansion?
+    def resolved_expansion
+      return unless @resolution || @current_parameter_expansion
+
+      { parameter: @current_parameter_expansion, inline: nil, include_chain: @current_include_chain }
+    end
   end
 end

data/lib/ibex/racc_migration/checker.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module RaccMigration
+    # Checks syntax, normalization, superclass, and runtime-coupling hazards.
+    # Semantic action code is treated as opaque data and never executed.
+    class Checker
+      RACC_REQUIRE = %r{(?:require|require_relative)\s*\(?\s*["']racc(?:/parser)?["']} #: Regexp
+      RACC_CONSTANT = /\bRacc::[A-Za-z_]\w*/ #: Regexp
+
+      # @rbs (String source, file: String) -> Report
+      def check(source, file:)
+        result = Frontend::Parser.new(source, file: file, mode: :default).parse_with_diagnostics
+        findings = result.diagnostics.map { |diagnostic| syntax_finding(diagnostic) }
+        ast = result.ast
+        return Report.new(file: file, class_name: nil, findings: findings) unless ast
+
+        findings.concat(superclass_findings(ast))
+        findings.concat(user_code_findings(ast))
+        findings.concat(normalization_findings(ast))
+        Report.new(file: file, class_name: ast.class_name, findings: sort_findings(findings))
+      end
+
+      private
+
+      # @rbs (Frontend::Diagnostic diagnostic) -> Finding
+      def syntax_finding(diagnostic)
+        Finding.new(
+          code: "racc.syntax",
+          severity: :error,
+          message: diagnostic.message,
+          location: diagnostic.location,
+          suggestion: "keep the grammar in default mode, or adopt the reported extension explicitly " \
+                      "with `pragma extended`"
+        )
+      end
+
+      # @rbs (Frontend::AST::Root ast) -> Array[Finding]
+      def superclass_findings(ast)
+        return [] unless ast.superclass&.start_with?("Racc::")
+
+        [
+          Finding.new(
+            code: "racc.runtime_superclass",
+            severity: :error,
+            message: "generated class inherits #{ast.superclass}",
+            location: ast.loc,
+            suggestion: "remove the explicit Racc superclass or generate with `--superclass=Ibex::Runtime::Parser`"
+          )
+        ]
+      end
+
+      # @rbs (Frontend::AST::Root ast) -> Array[Finding]
+      def user_code_findings(ast)
+        ast.user_code.values.flatten.flat_map do |chunk|
+          findings = [] #: Array[Finding]
+          if chunk.code.match?(RACC_REQUIRE)
+            findings << Finding.new(
+              code: "racc.runtime_require",
+              severity: :warning,
+              message: "user code requires the racc runtime",
+              location: chunk.loc,
+              suggestion: "remove this require after switching generated parsers to the Ibex runtime"
+            )
+          end
+          if chunk.code.match?(RACC_CONSTANT)
+            findings << Finding.new(
+              code: "racc.runtime_constant",
+              severity: :warning,
+              message: "user code references a Racc runtime constant",
+              location: chunk.loc,
+              suggestion: "replace the runtime-specific constant or keep an explicit compatibility adapter"
+            )
+          end
+          findings
+        end
+      end
+
+      # @rbs (Frontend::AST::Root ast) -> Array[Finding]
+      def normalization_findings(ast)
+        Normalizer.new(ast, mode: :default).normalize
+        []
+      rescue Ibex::Error => e
+        location, message = error_location(e.message, ast.loc)
+        [
+          Finding.new(
+            code: "racc.normalization",
+            severity: :error,
+            message: message,
+            location: location,
+            suggestion: "apply the diagnostic before generating either parser"
+          )
+        ]
+      end
+
+      # @rbs (String message, Frontend::Location fallback) -> [Frontend::Location, String]
+      def error_location(message, fallback)
+        match = message.match(/\A(.+):(\d+):(\d+): (.*)\z/m)
+        return [fallback, message] unless match
+
+        [
+          Frontend::Location.new(
+            file: match[1].to_s,
+            line: Integer(match[2].to_s, 10),
+            column: Integer(match[3].to_s, 10)
+          ),
+          match[4].to_s
+        ]
+      end
+
+      # @rbs (Array[Finding] findings) -> Array[Finding]
+      def sort_findings(findings)
+        rank = { error: 0, warning: 1, info: 2 }
+        findings.sort_by do |finding|
+          location = finding.location
+          [location&.file || "", location&.line || 0, location&.column || 0, rank.fetch(finding.severity), finding.code]
+        end
+      end
+    end
+  end
+end

data/lib/ibex/racc_migration/harness.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module RaccMigration
+    # Emits, but never executes, a subprocess-separated differential harness.
+    class Harness
+      CLASS_NAME = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/ #: Regexp
+
+      # @rbs (String class_name) -> String
+      def self.generate(class_name)
+        raise ArgumentError, "invalid parser class name #{class_name.inspect}" unless class_name.match?(CLASS_NAME)
+
+        template.sub("__PARSER_CLASS_NAME__", class_name.dump)
+      end
+
+      # @rbs () -> String
+      def self.template
+        <<~'RUBY'
+          #!/usr/bin/env ruby
+          # frozen_string_literal: true
+
+          # Generated migration differential harness.
+          # Running this file executes both generated parsers and all grammar
+          # user code in child Ruby processes. Review the grammar and CASES,
+          # then run this only in an isolation boundary you trust.
+
+          require "rbconfig"
+          require "tempfile"
+          require "tmpdir"
+
+          PARSER_CLASS = __PARSER_CLASS_NAME__
+          TIMEOUT_SECONDS = 15
+          MAX_OUTPUT_BYTES = 1_048_576
+          CASES = [
+            # { name: "example", tokens: [[:TOKEN, "value"], ["+", nil]] }
+          ].freeze
+
+          CHILD_RUNNER = <<~'CHILD'
+            begin
+              load ARGV.fetch(0)
+              parser_class = ARGV.fetch(1).split("::").inject(Object) { |scope, name| scope.const_get(name, false) }
+              tokens = Marshal.load(ARGV.fetch(2).unpack1("m0"))
+              parser = parser_class.new
+              parser.define_singleton_method(:next_token) { tokens.shift }
+              result = parser.do_parse
+              puts "IBEX_HARNESS_RESULT=#{[Marshal.dump([:ok, result])].pack("m0")}"
+            rescue StandardError => error
+              payload = [:error, error.class.name, error.message]
+              puts "IBEX_HARNESS_RESULT=#{[Marshal.dump(payload)].pack("m0")}"
+            end
+          CHILD
+
+          def terminate(pid)
+            Process.kill("TERM", pid)
+          rescue Errno::ESRCH
+            nil
+          ensure
+            deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 0.5
+            while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+              waited = Process.waitpid2(pid, Process::WNOHANG)
+              return waited.last if waited
+
+              sleep 0.01
+            end
+            Process.kill("KILL", pid)
+            Process.waitpid2(pid).last
+          end
+
+          def run_command(*command)
+            Tempfile.create("migration-stdout") do |stdout|
+              Tempfile.create("migration-stderr") do |stderr|
+                pid = Process.spawn(*command, out: stdout, err: stderr)
+                deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + TIMEOUT_SECONDS
+                status = nil
+                until status
+                  waited = Process.waitpid2(pid, Process::WNOHANG)
+                  status = waited.last if waited
+                  break if status
+                  if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+                    status = terminate(pid)
+                    stdout.rewind
+                    stderr.rewind
+                    return [
+                      stdout.read(MAX_OUTPUT_BYTES) || "", stderr.read(MAX_OUTPUT_BYTES) || "", status, true, false
+                    ]
+                  end
+                  if stdout.size > MAX_OUTPUT_BYTES || stderr.size > MAX_OUTPUT_BYTES
+                    status = terminate(pid)
+                    stdout.rewind
+                    stderr.rewind
+                    return [
+                      stdout.read(MAX_OUTPUT_BYTES) || "", stderr.read(MAX_OUTPUT_BYTES) || "", status, false, true
+                    ]
+                  end
+                  sleep 0.01
+                end
+                stdout.rewind
+                stderr.rewind
+                [
+                  stdout.read(MAX_OUTPUT_BYTES) || "", stderr.read(MAX_OUTPUT_BYTES) || "", status, false, false
+                ]
+              end
+            end
+          end
+
+          def compile!(label, *command)
+            stdout, stderr, status, timed_out, output_limited = run_command(*command)
+            abort "#{label} generation timed out" if timed_out
+            abort "#{label} generation exceeded #{MAX_OUTPUT_BYTES} output bytes" if output_limited
+            return if status.success?
+
+            abort "#{label} generation failed\n#{stdout}#{stderr}"
+          end
+
+          def observe(parser_path, tokens)
+            payload = [Marshal.dump(tokens)].pack("m0")
+            stdout, stderr, status, timed_out, output_limited = run_command(
+              RbConfig.ruby, "-e", CHILD_RUNNER, parser_path, PARSER_CLASS, payload
+            )
+            return { timeout: true } if timed_out
+            return { output_limit: MAX_OUTPUT_BYTES } if output_limited
+
+            lines = stdout.lines
+            marker = lines.reverse.find { |line| line.start_with?("IBEX_HARNESS_RESULT=") }
+            unless status.success? && marker
+              return {
+                infrastructure_error: File.basename(parser_path),
+                status: status.exitstatus,
+                stdout: stdout,
+                stderr: stderr
+              }
+            end
+            outcome = marker && Marshal.load(marker.split("=", 2).last.strip.unpack1("m0"))
+            {
+              status: status.exitstatus,
+              outcome: outcome,
+              stdout: lines.reject { |line| line.equal?(marker) }.join,
+              stderr: stderr
+            }
+          end
+
+          abort "add at least one reviewed entry to CASES before running the harness" if CASES.empty?
+          grammar = File.expand_path(ARGV.fetch(0))
+          abort "grammar file does not exist: #{grammar}" unless File.file?(grammar)
+          racc = ENV.fetch("RACC", "racc")
+          ibex = ENV.fetch("IBEX", "ibex")
+
+          failures = 0
+          Dir.mktmpdir("ibex-migration-harness-") do |directory|
+            racc_parser = File.join(directory, "racc_parser.rb")
+            ibex_parser = File.join(directory, "ibex_parser.rb")
+            compile!("racc", racc, "-o", racc_parser, grammar)
+            compile!("ibex", ibex, "-E", "-o", ibex_parser, grammar)
+
+            CASES.each do |test_case|
+              name = test_case.fetch(:name)
+              tokens = test_case.fetch(:tokens)
+              expected = observe(racc_parser, tokens)
+              actual = observe(ibex_parser, tokens)
+              if expected == actual
+                puts "ok #{name}"
+              else
+                failures += 1
+                warn "difference #{name}"
+                warn "  racc: #{expected.inspect}"
+                warn "  ibex: #{actual.inspect}"
+              end
+            end
+          end
+          exit(failures.zero? ? 0 : 1)
+        RUBY
+      end
+      private_class_method :template
+    end
+  end
+end

data/lib/ibex/racc_migration/report.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+module Ibex
+  module RaccMigration
+    # @rbs!
+    #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
+    # One immutable migration compatibility observation.
+    class Finding
+      SEVERITIES = %i[error warning info].freeze #: Array[Symbol]
+
+      attr_reader :code #: String
+      attr_reader :severity #: Symbol
+      attr_reader :message #: String
+      attr_reader :location #: Frontend::Location?
+      attr_reader :suggestion #: String
+
+      # @rbs (code: String, severity: Symbol, message: String, location: Frontend::Location?,
+      #   suggestion: String) -> void
+      def initialize(code:, severity:, message:, location:, suggestion:)
+        unless SEVERITIES.include?(severity)
+          raise ArgumentError, "unknown migration finding severity #{severity.inspect}"
+        end
+
+        @code = code.dup.freeze
+        @severity = severity
+        @message = message.dup.freeze
+        @location = location
+        @suggestion = suggestion.dup.freeze
+        freeze
+      end
+
+      # @rbs () -> Hash[String, json_value]
+      def to_h
+        {
+          "code" => @code,
+          "severity" => @severity.to_s,
+          "message" => @message,
+          "location" => @location&.to_h&.transform_keys(&:to_s),
+          "suggestion" => @suggestion
+        }
+      end
+    end
+
+    # Versioned result of checking one grammar without executing its code.
+    class Report
+      SCHEMA_VERSION = 1 #: Integer
+
+      attr_reader :file #: String
+      attr_reader :class_name #: String?
+      attr_reader :findings #: Array[Finding]
+
+      # @rbs (file: String, class_name: String?, findings: Array[Finding]) -> void
+      def initialize(file:, class_name:, findings:)
+        @file = file.dup.freeze
+        @class_name = class_name&.dup&.freeze
+        @findings = findings.dup.freeze
+        freeze
+      end
+
+      # @rbs () -> bool
+      def compatible? = @findings.none? { |finding| finding.severity == :error }
+
+      # @rbs () -> Hash[String, json_value]
+      def to_h
+        {
+          "ibex_migration_check" => "racc",
+          "schema_version" => SCHEMA_VERSION,
+          "compatible" => compatible?,
+          "file" => @file,
+          "class_name" => @class_name,
+          "findings" => @findings.map(&:to_h)
+        }
+      end
+
+      # @rbs (*Object?) -> String
+      def to_json(*) = JSON.pretty_generate(to_h)
+
+      # @rbs () -> String
+      def to_text
+        return "#{@file}: compatible with the checked racc migration surface\n" if @findings.empty?
+
+        lines = @findings.flat_map do |finding|
+          prefix = finding.location ? finding.location.to_s : "#{@file}:1:1"
+          [
+            "#{prefix}: #{finding.severity}: #{finding.message} [#{finding.code}]",
+            "  suggestion: #{finding.suggestion}"
+          ]
+        end
+        "#{lines.join("\n")}\n"
+      end
+    end
+  end
+end

data/lib/ibex/racc_migration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "racc_migration/report"
+require_relative "racc_migration/checker"
+require_relative "racc_migration/harness"
+
+module Ibex
+  # Static checks and explicitly generated differential tooling for migration
+  # from racc grammar files.
+  module RaccMigration
+  end
+end