ibex 0.2.0 → 0.3.0

data/lib/ibex/cli/analysis.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "optparse"
+require_relative "../diff"
+require_relative "../metrics"
+
+module Ibex
+  # CLI entry points for deterministic grammar diff and metrics reports.
+  module CLIAnalysis
+    # @rbs!
+    #   type analysis_options = Hash[Symbol, untyped]
+    #   private def normalize_grammar_path: (String) -> IR::Grammar
+    #   private def set_configuration_option: (Symbol, Object?) -> void
+    #   private def local_configuration_value: (Hash[Symbol, untyped], String) -> untyped
+    #   private def set_local_configuration_option: (Hash[Symbol, untyped], Symbol, untyped) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_diff_command(arguments)
+      settings = analysis_options(arguments, "diff", operands: "OLD NEW")
+      if settings[:help]
+        @stdout.puts(settings.fetch(:help))
+        return 0
+      end
+      paths = settings.fetch(:paths)
+      raise Ibex::Error, "(diff):1:1: diff requires exactly two grammar or IR files" unless paths.length == 2
+
+      algorithm = settings.fetch(:algorithm)
+      before = load_analysis_automaton(paths.fetch(0), algorithm, explicit: algo_set?(settings))
+      after = load_analysis_automaton(paths.fetch(1), algorithm, explicit: algo_set?(settings))
+      report = Diff.new(before, after).to_h
+      write_analysis_report(report, settings.fetch(:format))
+      0
+    end
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_metrics_command(arguments)
+      settings = analysis_options(arguments, "metrics", operands: "GRAMMAR")
+      if settings[:help]
+        @stdout.puts(settings.fetch(:help))
+        return 0
+      end
+      paths = settings.fetch(:paths)
+      raise Ibex::Error, "(metrics):1:1: metrics requires exactly one grammar or IR file" unless paths.length == 1
+
+      automaton = load_analysis_automaton(paths.fetch(0), settings.fetch(:algorithm), explicit: algo_set?(settings))
+      report = Metrics.new(automaton).to_h
+      write_analysis_report(report, settings.fetch(:format))
+      0
+    end
+
+    # @rbs (Array[String] arguments, String command, operands: String) -> Hash[Symbol, untyped]
+    def analysis_options(arguments, command, operands:)
+      settings = {
+        paths: [], algorithm: Configuration::Registry.fetch("parser.algorithm").default,
+        mode: Configuration::Registry.fetch("grammar.mode").default, format: "json", configuration_explicit: []
+      } #: Hash[Symbol, untyped]
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex #{command} [options] #{operands}"
+        options.on("--algorithm=NAME", %w[slr lalr ielr lr1], "algorithm for grammar inputs") do |value|
+          set_local_configuration_option(settings, :algorithm, value.to_sym)
+        end
+        options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+          set_configuration_option(:mode, value.to_sym)
+        end
+        options.on("--format=FORMAT", %w[json text], "json or text") { |value| settings[:format] = value }
+        options.on("--help", "show help") { settings[:help] = options.to_s }
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings[:algorithm] = local_configuration_value(settings, "parser.algorithm")
+      settings
+    end
+
+    # @rbs (String path, Symbol algorithm, explicit: bool) -> IR::Automaton
+    def load_analysis_automaton(path, algorithm, explicit:)
+      source = File.binread(path)
+      if source.lstrip.start_with?("{")
+        value = IR::Validator.validate(source)
+        if value.is_a?(IR::Automaton)
+          raise Ibex::Error, "(cli):1:1: --algorithm cannot be combined with Automaton IR analysis input" if explicit
+
+          return value
+        end
+        return build_analysis_automaton(value, algorithm, explicit) if value.is_a?(IR::Grammar)
+
+        raise Ibex::Error, "#{path}:1:1: analysis does not accept Lexer IR"
+      end
+
+      build_analysis_automaton(normalize_grammar_path(path), algorithm, explicit)
+    end
+
+    # @rbs (IR::Grammar grammar, Symbol algorithm, bool algorithm_explicit) -> IR::Automaton
+    def build_analysis_automaton(grammar, algorithm, algorithm_explicit)
+      explicit_keys = algorithm_explicit ? [:algorithm] : [] #: Array[Symbol]
+      active = activate_analysis_grammar(
+        grammar, options: { algorithm: algorithm }, explicit_keys: explicit_keys
+      )
+      LALR::Builder.new(
+        active, algorithm: configuration_value("parser.algorithm"),
+                entry_isolation: configuration_value("parser.entries") == :isolated
+      ).build
+    end
+
+    # @rbs (Hash[Symbol, untyped] report, String format) -> void
+    def write_analysis_report(report, format)
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(report))
+      elsif report.fetch(:ibex_report) == "metrics"
+        @stdout.puts("states=#{report.dig(:automaton, :states)} rules=#{report.dig(:grammar, :rules)} " \
+                     "alternatives=#{report.dig(:grammar, :alternatives)}")
+      else
+        %i[symbols rules conflicts warnings].each do |section|
+          values = report.fetch(section)
+          @stdout.puts("#{section}: +#{values.fetch(:added).length} " \
+                       "-#{values.fetch(:removed).length} ~#{values.fetch(:changed).length}")
+        end
+      end
+    end
+
+    # @rbs (Hash[Symbol, untyped] settings) -> bool
+    def algo_set?(settings)
+      settings.fetch(:configuration_explicit).include?(:algorithm)
+    end
+
+    # @rbs!
+    #   private def activate_analysis_grammar: (IR::Grammar, ?options: Hash[Symbol, untyped],
+    #     ?explicit_keys: Array[Symbol]) -> IR::Grammar
+    #   private def configuration_value: (String) -> untyped
+  end
+end

data/lib/ibex/cli/bison_import.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "optparse"
+require_relative "../bison_import"
+
+module Ibex
+  # CLI boundary for analysis-only Bison grammar import.
+  module CLIBisonImport
+    # @rbs!
+    #   type bison_import_options = {
+    #     format: String,
+    #     max_bytes: Integer,
+    #     max_tokens: Integer,
+    #     max_rules: Integer,
+    #     max_actions: Integer,
+    #     ?output: String,
+    #     ?class_name: String,
+    #     ?help: bool
+    #   }
+    #   private def same_file_target?: (String, String) -> bool
+    #   private def atomic_write_ir: (String, String) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_bison_import_command(arguments)
+      kind = arguments.shift
+      raise Ibex::Error, "(bison-import):1:1: import requires the `bison` format" unless kind == "bison"
+
+      settings = default_bison_import_options
+      parser = bison_import_option_parser(settings)
+      paths = parser.parse(arguments)
+      if settings[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+      raise Ibex::Error, "(bison-import):1:1: import bison requires exactly one source file" unless paths.length == 1
+
+      path = paths.fetch(0)
+      result = build_bison_import(path, settings)
+      rendered = settings.fetch(:format) == "json" ? "#{JSON.pretty_generate(result.to_h)}\n" : result.source
+      write_bison_import(path, settings[:output], rendered)
+      0
+    rescue BisonImport::BudgetExceeded => e
+      @stdout.puts(JSON.pretty_generate({ ibex_report: "bison_import", schema_version: 1 }.merge(e.details)))
+      2
+    end
+
+    # @rbs () -> bison_import_options
+    def default_bison_import_options
+      {
+        format: "source",
+        max_bytes: BisonImport::Importer::DEFAULT_MAX_BYTES,
+        max_tokens: BisonImport::Importer::DEFAULT_MAX_TOKENS,
+        max_rules: BisonImport::Importer::DEFAULT_MAX_RULES,
+        max_actions: BisonImport::Importer::DEFAULT_MAX_ACTIONS
+      }
+    end
+
+    # @rbs (bison_import_options settings) -> OptionParser
+    def bison_import_option_parser(settings)
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex import bison [options] grammar.y"
+        options.on("--format=FORMAT", %w[source json], "converted source or JSON report") do |value|
+          settings[:format] = value
+        end
+        options.on("-o FILE", "--output=FILE", "write atomically to FILE") { |value| settings[:output] = value }
+        options.on("--class=NAME", "generated analysis grammar class") { |value| settings[:class_name] = value }
+        add_bison_import_budgets(options, settings)
+        options.on("--help", "show help") { settings[:help] = true }
+      end
+    end
+
+    # @rbs (OptionParser options, bison_import_options settings) -> void
+    def add_bison_import_budgets(options, settings)
+      {
+        "max-bytes" => :max_bytes,
+        "max-tokens" => :max_tokens,
+        "max-rules" => :max_rules,
+        "max-actions" => :max_actions
+      }.each do |name, key|
+        options.on("--#{name}=N", Integer, "positive import budget") do |value|
+          raise OptionParser::InvalidArgument, "--#{name} must be positive" unless value.positive?
+
+          settings[key] = value
+        end
+      end
+    end
+
+    # @rbs (String path, bison_import_options settings) -> BisonImport::Result
+    def build_bison_import(path, settings)
+      BisonImport::Importer.new(
+        File.binread(path),
+        file: path,
+        class_name: settings[:class_name],
+        max_bytes: settings.fetch(:max_bytes),
+        max_tokens: settings.fetch(:max_tokens),
+        max_rules: settings.fetch(:max_rules),
+        max_actions: settings.fetch(:max_actions)
+      ).run
+    end
+
+    # @rbs (String input, String? output, String source) -> void
+    def write_bison_import(input, output, source)
+      unless output
+        @stdout.write(source)
+        return
+      end
+      if same_file_target?(input, output)
+        raise Ibex::Error, "(bison-import):1:1: import input and output paths must be distinct"
+      end
+      if File.symlink?(output) || (File.exist?(output) && File.stat(output).nlink > 1)
+        raise Ibex::Error, "(bison-import):1:1: output refuses symlink aliases and files with multiple hard links"
+      end
+
+      atomic_write_ir(output, source)
+    end
+  end
+end

data/lib/ibex/cli/config.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "optparse"
+require_relative "../configuration/inspector"
+require_relative "../frontend/source_loader"
+require_relative "../frontend/resolver"
+require_relative "../ir/validator"
+
+module Ibex
+  # Static effective-configuration reporting for source grammars and Grammar IR.
+  module CLIConfig
+    # @rbs!
+    #   type config_options = {
+    #     format: String,
+    #     mode: Symbol,
+    #     configuration_explicit: Array[Symbol],
+    #     ?from: String,
+    #     ?algorithm: Symbol,
+    #     ?entry_isolation: bool,
+    #     ?cst_trivia: Symbol,
+    #     ?superclass: String,
+    #     ?omit_actions: bool,
+    #     ?help: String
+    #   }
+    #   private def input_path: (Array[String]) -> String
+    #   private def set_local_configuration_option: (Hash[Symbol, Object?], Symbol, Object?) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_config_command(arguments)
+      settings, paths = config_options(arguments)
+      if settings[:help]
+        @stdout.puts(settings.fetch(:help))
+        return 0
+      end
+
+      path = input_path(paths)
+      input = load_configuration_input(path, settings)
+      cli_values = Configuration::CLIAdapter.new(
+        settings, explicit_keys: settings.fetch(:configuration_explicit)
+      ).configuration_values
+      report = Configuration::Report.new(input, cli: cli_values)
+      write_configuration_report(report, settings.fetch(:format))
+      return 0 if report.success?
+
+      report.conflicts.each do |conflict|
+        @stderr.puts(Messages.translate("cli.error", language: @language, detail: conflict.message))
+      end
+      1
+    end
+
+    # @rbs (Array[String] arguments) -> [config_options, Array[String]]
+    def config_options(arguments)
+      settings = {
+        format: "text", mode: Configuration::Registry.fetch("grammar.mode").default,
+        configuration_explicit: []
+      } #: config_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex config [options] grammarfile"
+        add_config_options(options, settings)
+      end
+      [settings, parser.parse(arguments)]
+    end
+
+    # @rbs (OptionParser options, config_options settings) -> void
+    def add_config_options(options, settings)
+      options.on("--format=FORMAT", %w[text json], "text or json (default: text)") do |value|
+        settings[:format] = value
+      end
+      options.on("--from=FORMAT", %w[grammar-ir], "read validated Grammar IR JSON") do |value|
+        settings[:from] = value
+      end
+      add_config_contract_options(options, settings)
+      options.on("--help", "show help") { settings[:help] = options.to_s }
+    end
+
+    # @rbs (OptionParser options, config_options settings) -> void
+    def add_config_contract_options(options, settings)
+      options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+        set_local_configuration_option(settings, :mode, value.to_sym)
+      end
+      options.on("--algorithm=NAME", %w[slr lalr ielr lr1], "parser construction algorithm") do |value|
+        set_local_configuration_option(settings, :algorithm, value.to_sym)
+      end
+      options.on("--entry-isolation", "build independent state sets for each start symbol") do
+        set_local_configuration_option(settings, :entry_isolation, true)
+      end
+      options.on("--cst-trivia=POLICY", %w[leading balanced drop attach], "CST trivia policy") do |value|
+        set_local_configuration_option(settings, :cst_trivia, value.to_sym)
+      end
+      options.on("--superclass=CLASS", "request a parser superclass") do |value|
+        set_local_configuration_option(settings, :superclass, value)
+      end
+      options.on("--no-omit-actions", "generate implicit action methods") do
+        set_local_configuration_option(settings, :omit_actions, false)
+      end
+    end
+
+    # @rbs (String path, config_options settings) -> Configuration::Input
+    def load_configuration_input(path, settings)
+      return load_grammar_ir_configuration(path) if settings[:from] == "grammar-ir"
+
+      loader = Frontend::SourceLoader.new(record_reads: true)
+      resolver = Frontend::Resolver.new(path, mode: settings.fetch(:mode), loader: loader)
+      Configuration::Inspector.from_source(resolver.resolve)
+    end
+
+    # @rbs (String path) -> Configuration::Input
+    def load_grammar_ir_configuration(path)
+      value = IR::Validator.validate(File.binread(path))
+      raise Ibex::Error, "#{path}:1:1: expected grammar-ir input" unless value.is_a?(IR::Grammar)
+
+      Configuration::Inspector.from_grammar_ir(value, path: path)
+    end
+
+    # @rbs (Configuration::Report report, String format) -> void
+    def write_configuration_report(report, format)
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(report.to_h))
+      else
+        @stdout.write(report.render_text)
+      end
+    end
+  end
+end

data/lib/ibex/cli/diagnostics.rb

@@ -11,24 +11,23 @@ module Ibex
     DEFAULT_MAX_DIAGNOSTICS = 20 #: Integer
 
     # @rbs!
-    #   type diagnostic_settings = {
-    #     format: String,
-    #     max_diagnostics: Integer,
-    #     mode: Symbol,
-    #     ?help: bool
-    #   }
+    #   type diagnostic_settings = Hash[Symbol, untyped]
     #
     #   private def input_path: (Array[String]) -> String
+    #   private def local_configuration_value: (Hash[Symbol, Object?], String) -> Object?
+    #   private def set_local_configuration_option: (Hash[Symbol, Object?], Symbol, Object?) -> void
 
     private
 
     # @rbs (Array[String] arguments) -> Integer
     def run_diagnose_command(arguments)
       settings = {
-        format: "text", max_diagnostics: DEFAULT_MAX_DIAGNOSTICS, mode: :default
+        format: "text", max_diagnostics: DEFAULT_MAX_DIAGNOSTICS,
+        mode: Configuration::Registry.fetch("grammar.mode").default, configuration_explicit: []
       } #: diagnostic_settings
       parser = diagnostics_option_parser(settings)
       remaining = parser.parse(arguments)
+      settings[:mode] = local_configuration_value(settings, "grammar.mode")
       if settings[:help]
         @stdout.puts(parser)
         return 0
@@ -78,7 +77,9 @@ module Ibex
         options.on("--max-diagnostics=N", "positive diagnostic limit") do |value|
           settings[:max_diagnostics] = positive_diagnostic_limit(value)
         end
-        options.on("--mode=MODE", %w[default extended], "grammar mode") { |value| settings[:mode] = value.to_sym }
+        options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+        end
         options.on("--help", "show help") { settings[:help] = true }
       end
     end
@@ -98,19 +99,38 @@ module Ibex
       if format == "json"
         @stdout.puts(JSON.pretty_generate(diagnostics_document(result)))
       else
-        result.diagnostics.each { |diagnostic| @stdout.puts(diagnostic.to_s) }
+        result.diagnostics.each { |diagnostic| @stdout.puts(localized_diagnostic_text(diagnostic)) }
       end
     end
 
-    # @rbs (Frontend::ParseResult result) -> Hash[String, untyped]
+    # @rbs (Frontend::ParseResult result) -> Hash[String, Object?]
     def diagnostics_document(result)
       {
         "ibex_diagnostics" => "frontend",
         "schema_version" => DIAGNOSTICS_SCHEMA_VERSION,
         "success" => result.success?,
         "ast_available" => !result.ast.nil?,
-        "diagnostics" => result.diagnostics.map(&:to_h)
+        "diagnostics" => result.diagnostics.map { |diagnostic| localized_diagnostic_hash(diagnostic) }
       }
     end
+
+    # @rbs (Frontend::Diagnostic diagnostic) -> String
+    def localized_diagnostic_text(diagnostic)
+      return diagnostic.to_s if @language == "en"
+
+      "#{diagnostic.location}: #{localized_diagnostic_message(diagnostic)}"
+    end
+
+    # @rbs (Frontend::Diagnostic diagnostic) -> Hash[Symbol, Object?]
+    def localized_diagnostic_hash(diagnostic)
+      diagnostic.to_h.merge(message: localized_diagnostic_message(diagnostic))
+    end
+
+    # @rbs (Frontend::Diagnostic diagnostic) -> String
+    def localized_diagnostic_message(diagnostic)
+      id = "diagnostic.#{diagnostic.code}"
+      id = "diagnostic.generic" unless Messages.known?(id)
+      Messages.translate(id, language: @language, detail: diagnostic.message)
+    end
   end
 end

data/lib/ibex/cli/documentation.rb

@@ -9,24 +9,25 @@ module Ibex
   # Generates standalone grammar documentation from the canonical include closure.
   module CLIDocumentation
     # @rbs!
-    #   type documentation_settings = {
-    #     format: String,
-    #     mode: Symbol,
-    #     ?output: String,
-    #     ?help: bool
-    #   }
+    #   type documentation_settings = Hash[Symbol, untyped]
     #
     #   private def input_path: (Array[String]) -> String
     #   private def same_file_target?: (String left, String right) -> bool
     #   private def atomic_write_ir: (String path, String source) -> void
+    #   private def local_configuration_value: (Hash[Symbol, Object?], String) -> Object?
+    #   private def set_local_configuration_option: (Hash[Symbol, Object?], Symbol, Object?) -> void
 
     private
 
     # @rbs (Array[String] arguments) -> Integer
     def run_documentation_command(arguments)
-      settings = { format: "markdown", mode: :default } #: documentation_settings
+      settings = {
+        format: "markdown", mode: Configuration::Registry.fetch("grammar.mode").default,
+        configuration_explicit: []
+      } #: documentation_settings
       parser = documentation_option_parser(settings)
       remaining = parser.parse(arguments)
+      settings[:mode] = local_configuration_value(settings, "grammar.mode")
       if settings[:help]
         @stdout.puts(parser)
         return 0
@@ -59,7 +60,9 @@ module Ibex
           settings[:format] = value
         end
         options.on("-o FILE", "--output=FILE", "write atomically to FILE") { |value| settings[:output] = value }
-        options.on("--mode=MODE", %w[default extended], "grammar mode") { |value| settings[:mode] = value.to_sym }
+        options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+        end
         options.on("--help", "show help") { settings[:help] = true }
       end
     end

data/lib/ibex/cli/equiv.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "optparse"
+require_relative "../equiv"
+
+module Ibex
+  # CLI entry point for bounded language comparison.
+  module CLIEquiv
+    # @rbs!
+    #   type equiv_options = Hash[Symbol, untyped]
+    #   private def normalize_grammar_path: (String) -> IR::Grammar
+    #   private def configuration_value: (String) -> untyped
+    #   private def set_configuration_option: (Symbol, Object?) -> void
+    #   private def local_configuration_value: (Hash[Symbol, Object?], String) -> Object?
+    #   private def set_local_configuration_option: (Hash[Symbol, Object?], Symbol, Object?) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_equiv_command(arguments)
+      settings = equiv_options(arguments)
+      if settings[:help]
+        @stdout.puts(settings.fetch(:help))
+        return 0
+      end
+      paths = settings.fetch(:paths)
+      raise Ibex::Error, "(equiv):1:1: equiv requires exactly two grammar or IR files" unless paths.length == 2
+
+      algorithm = settings.fetch(:algorithm)
+      left = load_equiv_automaton(paths.fetch(0), algorithm, explicit: algorithm_explicit_equiv?(settings))
+      right = load_equiv_automaton(paths.fetch(1), algorithm, explicit: algorithm_explicit_equiv?(settings))
+      comparison = Equiv.new(
+        left, right,
+        sample_count: settings.fetch(:sample_count), seed: settings.fetch(:seed),
+        max_tokens: settings.fetch(:max_tokens), max_configurations: settings.fetch(:max_configurations),
+        max_actions: settings.fetch(:max_actions), max_stack: settings.fetch(:max_stack),
+        rule_map: settings.fetch(:rule_map)
+      )
+      write_equiv_report(comparison.run, settings.fetch(:format))
+      0
+    rescue Equiv::Difference => e
+      write_equiv_report(e.details, settings&.fetch(:format) || "json")
+      1
+    rescue Equiv::BudgetExceeded => e
+      report = { ibex_report: "equiv", schema_version: 1 }.merge(e.details)
+      write_equiv_report(report, settings&.fetch(:format) || "json")
+      2
+    end
+
+    # @rbs (Array[String] arguments) -> equiv_options
+    def equiv_options(arguments)
+      settings = default_equiv_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex equiv [options] LEFT RIGHT"
+        add_equiv_search_options(options, settings)
+        options.on("--algorithm=NAME", %w[slr lalr ielr lr1], "algorithm for grammar inputs") do |value|
+          set_local_configuration_option(settings, :algorithm, value.to_sym)
+        end
+        options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+          set_configuration_option(:mode, value.to_sym)
+        end
+        options.on("--map=OLD=NEW", "declare a nonterminal correspondence; repeatable") do |value|
+          old_name, new_name = value.split("=", 2)
+          if old_name.nil? || old_name.empty? || new_name.nil? || new_name.empty?
+            raise OptionParser::InvalidArgument, "--map must be OLD=NEW"
+          end
+
+          settings.fetch(:rule_map)[old_name] = new_name
+        end
+        options.on("--format=FORMAT", %w[json text], "json or text") { |value| settings[:format] = value }
+        options.on("--help", "show help") { settings[:help] = options.to_s }
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings[:algorithm] = local_configuration_value(settings, "parser.algorithm")
+      settings
+    end
+
+    # @rbs () -> equiv_options
+    def default_equiv_options
+      {
+        paths: [], sample_count: 100, seed: 0, max_tokens: 8, max_configurations: 50_000,
+        max_actions: Equiv::DEFAULT_MAX_ACTIONS, max_stack: Equiv::DEFAULT_MAX_STACK,
+        algorithm: Configuration::Registry.fetch("parser.algorithm").default,
+        mode: Configuration::Registry.fetch("grammar.mode").default, format: "json", rule_map: {},
+        configuration_explicit: []
+      }
+    end
+
+    # @rbs (OptionParser options, equiv_options settings) -> void
+    def add_equiv_search_options(options, settings)
+      options.on("--samples=N", Integer, "samples generated in each direction") do |value|
+        settings[:sample_count] = positive_equiv_option(value, "samples")
+      end
+      options.on("--seed=N", Integer, "deterministic sampling seed") { |value| settings[:seed] = value }
+      options.on("--max-tokens=N", Integer, "maximum counterexample length") do |value|
+        settings[:max_tokens] = positive_equiv_option(value, "max-tokens")
+      end
+      options.on("--max-configurations=N", Integer, "product-state exploration budget") do |value|
+        settings[:max_configurations] = positive_equiv_option(value, "max-configurations")
+      end
+      options.on("--max-actions=N", Integer, "actions per simulated token sequence") do |value|
+        settings[:max_actions] = positive_equiv_option(value, "max-actions")
+      end
+      options.on("--max-stack=N", Integer, "simulated parser stack depth") do |value|
+        settings[:max_stack] = positive_equiv_option(value, "max-stack")
+      end
+    end
+
+    # @rbs (String path, Symbol algorithm, explicit: bool) -> IR::Automaton
+    def load_equiv_automaton(path, algorithm, explicit:)
+      source = File.binread(path)
+      if source.lstrip.start_with?("{")
+        value = IR::Validator.validate(source)
+        if value.is_a?(IR::Automaton)
+          raise Ibex::Error, "(cli):1:1: --algorithm cannot be combined with Automaton IR analysis input" if explicit
+
+          return value
+        end
+        return build_equiv_automaton(value, algorithm, explicit) if value.is_a?(IR::Grammar)
+
+        raise Ibex::Error, "#{path}:1:1: equiv does not accept Lexer IR"
+      end
+
+      build_equiv_automaton(normalize_grammar_path(path), algorithm, explicit)
+    end
+
+    # @rbs (IR::Grammar grammar, Symbol algorithm, bool algorithm_explicit) -> IR::Automaton
+    def build_equiv_automaton(grammar, algorithm, algorithm_explicit)
+      explicit_keys = algorithm_explicit ? [:algorithm] : [] #: Array[Symbol]
+      active = activate_analysis_grammar(
+        grammar, options: { algorithm: algorithm }, explicit_keys: explicit_keys
+      )
+      LALR::Builder.new(
+        active, algorithm: configuration_value("parser.algorithm"),
+                entry_isolation: configuration_value("parser.entries") == :isolated
+      ).build
+    end
+
+    # @rbs (Hash[Symbol, Object?] report, String format) -> void
+    def write_equiv_report(report, format)
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(report))
+      else
+        @stdout.puts("result=#{report.fetch(:result)}")
+        @stdout.puts("witness=#{report[:witness].inspect}") if report[:witness]
+        @stdout.puts(report.fetch(:statement))
+      end
+    end
+
+    # @rbs (equiv_options settings) -> bool
+    def algorithm_explicit_equiv?(settings)
+      settings.fetch(:configuration_explicit).include?(:algorithm)
+    end
+
+    # @rbs!
+    #   private def activate_analysis_grammar: (IR::Grammar, ?options: Hash[Symbol, Object?],
+    #     ?explicit_keys: Array[Symbol]) -> IR::Grammar
+
+    # @rbs (Integer value, String name) -> Integer
+    def positive_equiv_option(value, name)
+      return value if value.positive?
+
+      raise OptionParser::InvalidArgument, "--#{name} must be positive"
+    end
+  end
+end