ibex 0.1.0 → 0.3.0

data/lib/ibex/cli/diagnostics.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../frontend"
+
+module Ibex
+  # Batch frontend diagnostics subcommand.
+  module CLIDiagnostics
+    DIAGNOSTICS_SCHEMA_VERSION = 1 #: Integer
+    DEFAULT_MAX_DIAGNOSTICS = 20 #: Integer
+
+    # @rbs!
+    #   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: 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
+      end
+
+      path = input_path(remaining)
+      result = Frontend::Parser.new(File.binread(path), file: path, mode: settings.fetch(:mode))
+                               .parse_with_diagnostics(max_diagnostics: settings.fetch(:max_diagnostics))
+      result = resolve_diagnostic_result(result, path, settings.fetch(:mode)) if result.success?
+      write_diagnostics(result, format: settings.fetch(:format))
+      result.success? ? 0 : 1
+    end
+
+    # Cross-file recovery is deliberately bounded to the first resolver error.
+    # @rbs (Frontend::ParseResult result, String path, Symbol mode) -> Frontend::ParseResult
+    def resolve_diagnostic_result(result, path, mode)
+      Frontend::Resolver.new(path, mode: mode).resolve
+      result
+    rescue Frontend::ResolutionIOError
+      raise
+    rescue Ibex::Error => e
+      Frontend::ParseResult.new(diagnostics: [resolution_diagnostic(e, path)], ast: nil, document: nil)
+    end
+
+    # @rbs (Ibex::Error error, String fallback_file) -> Frontend::Diagnostic
+    def resolution_diagnostic(error, fallback_file)
+      match = error.message.match(/\A(.+):(\d+):(\d+): (.*)\z/m)
+      location = if match
+                   Frontend::Location.new(
+                     file: match[1].to_s, line: Integer(match[2].to_s), column: Integer(match[3].to_s)
+                   )
+                 else
+                   Frontend::Location.new(file: fallback_file, line: 1, column: 1)
+                 end
+      message = match ? match[4].to_s : error.message
+      Frontend::Diagnostic.new(
+        code: "frontend.resolution_error", phase: :syntax, message: message,
+        location: location, rendered: error.message
+      )
+    end
+
+    # @rbs (diagnostic_settings settings) -> OptionParser
+    def diagnostics_option_parser(settings)
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex diagnose [options] grammarfile"
+        options.on("--format=FORMAT", %w[text json], "text or json") { |value| settings[:format] = value }
+        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") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+        end
+        options.on("--help", "show help") { settings[:help] = true }
+      end
+    end
+
+    # @rbs (String value) -> Integer
+    def positive_diagnostic_limit(value)
+      limit = Integer(value, 10)
+      return limit if limit.positive?
+
+      raise OptionParser::InvalidArgument, "max diagnostics must be positive"
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "max diagnostics must be a positive integer"
+    end
+
+    # @rbs (Frontend::ParseResult result, format: String) -> void
+    def write_diagnostics(result, format:)
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(diagnostics_document(result)))
+      else
+        result.diagnostics.each { |diagnostic| @stdout.puts(localized_diagnostic_text(diagnostic)) }
+      end
+    end
+
+    # @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 { |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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../frontend"
+require_relative "../normalize"
+require_relative "../codegen/documentation"
+
+module Ibex
+  # Generates standalone grammar documentation from the canonical include closure.
+  module CLIDocumentation
+    # @rbs!
+    #   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: 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
+      end
+
+      path = input_path(remaining)
+      output = settings[:output]
+      resolution = Frontend::Resolver.new(path, mode: settings.fetch(:mode)).resolve
+      reject_documentation_output_collision(output, resolution.files) if output
+      grammar = Normalizer.new(resolution, mode: settings.fetch(:mode)).normalize
+      rendered = Codegen::Documentation.render(grammar, format: settings.fetch(:format))
+      output ? atomic_write_ir(output, rendered) : @stdout.write(rendered)
+      0
+    end
+
+    # @rbs (String output, Array[String] grammar_files) -> void
+    def reject_documentation_output_collision(output, grammar_files)
+      collision = grammar_files.find { |grammar_file| same_file_target?(grammar_file, output) }
+      return unless collision
+
+      raise Ibex::Error,
+            "(cli):1:1: doc input and output paths must be distinct; output aliases grammar source #{collision}"
+    end
+
+    # @rbs (documentation_settings settings) -> OptionParser
+    def documentation_option_parser(settings)
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex doc [options] grammarfile"
+        options.on("--format=FORMAT", Codegen::Documentation::FORMATS, "markdown, html, or railroad") do |value|
+          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") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+        end
+        options.on("--help", "show help") { settings[:help] = true }
+      end
+    end
+  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

data/lib/ibex/cli/error_messages.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require_relative "../error_messages"
+require_relative "../ir"
+
+module Ibex
+  # CLI subcommand and generation-file handling for example-keyed errors.
+  module CLIErrorMessages
+    # @rbs!
+    #   private def print_help: (OptionParser) -> Integer
+    #   private def input_path: (Array[String]) -> String
+    #   private def warning_categories: (String) -> Array[Symbol]
+    #   private def report_status: (String) -> void
+    #   private def handle_grammar_warnings: (IR::Grammar, String) -> void
+    #   private def build_automaton: (IR::Grammar, String) -> IR::Automaton
+    #   private def prepare_loaded_automaton: (IR::Automaton, String) -> void
+    #   private def default_output_path: (String, String) -> String
+    #   private def same_file_target?: (String, String) -> bool
+    #   private def normalize_grammar_path: (String) -> IR::Grammar
+    #   private def record_generation_input: (String, String) -> GenerationInput
+    #   private def select_configuration_mode: (String) -> void
+    #   private def set_configuration_option: (Symbol, Object?) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_error_messages_command(arguments)
+      parser = error_messages_option_parser
+      remaining = parser.parse(arguments)
+      return print_help(parser) if @options[:help]
+      if @options[:messages_list] && @options[:messages_update]
+        raise Ibex::Error, "(cli):1:1: errors command accepts only one of --list or --update"
+      end
+      unless @options[:messages_list] || @options[:messages_update]
+        raise Ibex::Error, "(cli):1:1: errors command requires --list or --update[=FILE]"
+      end
+
+      input = input_path(remaining)
+      automaton = automaton_for_error_messages(input)
+      if @options[:messages_list]
+        @stdout.write(ErrorMessages.render(automaton, **error_message_search_limits))
+      else
+        write_error_messages(automaton, input)
+      end
+      0
+    end
+
+    # @rbs () -> OptionParser
+    def error_messages_option_parser
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex errors (--list | --update[=FILE]) [options] grammarfile"
+        options.on("--list", "list shortest error sentences on stdout") { @options[:messages_list] = true }
+        options.on("--update[=FILE]", "update messages (defaults to grammar.messages)") do |value|
+          @options[:messages_update] = value || true
+        end
+        options.on("--max-tokens=N", Integer, "maximum error-sentence token budget") do |value|
+          @options[:messages_max_tokens] = positive_messages_limit(value, "--max-tokens")
+        end
+        options.on("--max-configurations=N", Integer, "maximum error-sentence configuration budget") do |value|
+          @options[:messages_max_configurations] = positive_messages_limit(value, "--max-configurations")
+        end
+        options.on("--from=FORMAT", %w[grammar-ir automaton-ir], "resume from IR JSON") do |value|
+          @options[:from] = value
+        end
+        options.on("--mode=MODE", %w[default extended], "grammar mode") { |value| select_configuration_mode(value) }
+        options.on("--algorithm=NAME", %w[slr lalr ielr lr1], "parser construction algorithm") do |value|
+          set_configuration_option(:algorithm, value.to_sym)
+          @options[:messages_algorithm_explicit] = true
+        end
+        options.on("--warnings=CATEGORIES", "all, error, all,error, or none") do |value|
+          @options[:warnings] = warning_categories(value)
+        end
+        options.on("-S", "--output-status", "show pipeline status") { @options[:status] = true }
+        options.on("--help", "show help") { @options[:help] = true }
+      end
+    end
+
+    # @rbs (String input_path) -> IR::Automaton
+    def automaton_for_error_messages(input_path)
+      return automaton_from_ir_for_messages(input_path) if @options[:from]
+
+      report_status("reading #{input_path}")
+      grammar = normalize_grammar_path(input_path)
+      grammar = activate_analysis_grammar(grammar)
+      handle_grammar_warnings(grammar, input_path)
+      build_automaton(grammar, input_path)
+    end
+
+    # @rbs (String input_path) -> IR::Automaton
+    def automaton_from_ir_for_messages(input_path)
+      report_status("reading #{input_path}")
+      value = IR::Validator.validate(File.read(input_path))
+      expected = @options[:from] == "grammar-ir" ? IR::Grammar : IR::Automaton
+      raise Ibex::Error, "#{input_path}:1:1: expected #{@options[:from]} input" unless value.is_a?(expected)
+      if value.is_a?(IR::Automaton) && @options[:messages_algorithm_explicit]
+        raise Ibex::Error, "(cli):1:1: --algorithm cannot be combined with --from=automaton-ir"
+      end
+
+      grammar = if value.is_a?(IR::Grammar)
+                  activate_analysis_grammar(value)
+                elsif value.is_a?(IR::Automaton)
+                  value.grammar
+                else
+                  raise Ibex::Error, "#{input_path}:1:1: expected #{@options[:from]} input"
+                end
+      handle_grammar_warnings(grammar, input_path)
+      return build_automaton(grammar, input_path) if value.is_a?(IR::Grammar)
+
+      if value.is_a?(IR::Automaton)
+        prepare_loaded_automaton(value, input_path)
+        return value
+      end
+
+      raise Ibex::Error, "#{input_path}:1:1: expected #{@options[:from]} input"
+    end
+
+    # @rbs (IR::Automaton automaton, String input_path) -> void
+    def write_error_messages(automaton, input_path)
+      configured = @options[:messages_update]
+      path = configured == true ? default_output_path(input_path, ".messages") : configured
+      raise Ibex::Error, "(cli):1:1: messages update path must not be empty" unless path.is_a?(String) && !path.empty?
+      if same_file_target?(path, input_path)
+        raise Ibex::Error, "(cli):1:1: messages update path must differ from the input path"
+      end
+
+      existing = if File.exist?(path)
+                   ErrorMessages.load(path)
+                 else
+                   ErrorMessages::Document.new(entries: [])
+                 end
+      update = ErrorMessages.update(automaton, existing: existing, **error_message_search_limits)
+      target_path = File.symlink?(path) ? File.realpath(path) : path
+      directory = File.dirname(File.expand_path(target_path))
+      Tempfile.create([".ibex-messages-", ".tmp"], directory, encoding: "UTF-8") do |file|
+        file.write(update.source)
+        File.chmod(messages_file_mode(target_path), file.path)
+        file.flush
+        file.fsync
+        File.rename(file.path, target_path)
+      end
+      write_error_message_update_report(update)
+      report_status("wrote #{path}")
+    end
+
+    # @rbs () -> { max_tokens: Integer, max_configurations: Integer }
+    def error_message_search_limits
+      {
+        max_tokens: @options.fetch(:messages_max_tokens, ErrorMessages::SentenceSearch::DEFAULT_MAX_TOKENS),
+        max_configurations: @options.fetch(
+          :messages_max_configurations, ErrorMessages::SentenceSearch::DEFAULT_MAX_CONFIGURATIONS
+        )
+      }
+    end
+
+    # @rbs (Integer value, String option) -> Integer
+    def positive_messages_limit(value, option)
+      return value if value.positive?
+
+      raise Ibex::Error, "(cli):1:1: #{option} must be positive"
+    end
+
+    # @rbs (ErrorMessages::Update update) -> void
+    def write_error_message_update_report(update)
+      classifications = {
+        "uncovered" => update.uncovered, "unreachable" => update.unreachable, "moved" => update.moved
+      }
+      classifications.each do |label, items|
+        items.each { |item| @stdout.puts("#{label}: #{item}") }
+      end
+    end
+
+    # @rbs (String path) -> Integer
+    def messages_file_mode(path)
+      return File.stat(path).mode & 0o777 if File.exist?(path)
+
+      0o666 & ~File.umask
+    end
+
+    # @rbs!
+    #   private def activate_analysis_grammar: (IR::Grammar, ?options: Hash[Symbol, Object?],
+    #     ?explicit_keys: Array[Symbol]) -> IR::Grammar
+  end
+end

data/lib/ibex/cli/explain.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../codegen/explain"
+
+module Ibex
+  # Dedicated command-line view for selected parser conflicts.
+  module CLIExplain
+    # @rbs!
+    #   private def print_help: (OptionParser) -> Integer
+    #   private def input_path: (Array[String]) -> String
+    #   private def positive_counterexample_limit: (Integer, String) -> Integer
+    #   private def normalize_grammar_path: (String) -> IR::Grammar
+    #   private def configuration_value: (String) -> untyped
+    #   private def set_configuration_option: (Symbol, Object?) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_explain_command(arguments)
+      parser = explain_option_parser
+      remaining = parser.parse(arguments)
+      return print_help(parser) if @options[:help]
+
+      path = input_path(remaining)
+      grammar = activate_analysis_grammar(normalize_grammar_path(path))
+      automaton = LALR::Builder.new(
+        grammar, algorithm: configuration_value("parser.algorithm"),
+                 entry_isolation: configuration_value("parser.entries") == :isolated
+      ).build
+      explanation = Codegen::Explain.new(
+        automaton, state: @options[:explain_state], token: @options[:explain_token],
+                   max_tokens: @options.fetch(:counterexample_max_tokens),
+                   max_configurations: @options.fetch(:counterexample_max_configurations)
+      )
+      output = @options[:explain_format] == "json" ? JSON.pretty_generate(explanation.to_h) : explanation.render_text
+      @stdout.puts(output)
+      0
+    end
+
+    # @rbs () -> OptionParser
+    def explain_option_parser
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex explain [options] grammarfile"
+        options.on("--state=N", Integer, "select one automaton state") { |value| @options[:explain_state] = value }
+        options.on("--token=NAME", "select a grammar token name or exact display name") do |value|
+          @options[:explain_token] = value
+        end
+        options.on("--format=FORMAT", %w[text json], "text or json (default: text)") do |value|
+          @options[:explain_format] = value
+        end
+        options.on("--algorithm=NAME", %w[slr lalr ielr lr1], "parser construction algorithm") do |value|
+          set_configuration_option(:algorithm, value.to_sym)
+        end
+        options.on("--entry-isolation", "build independent state sets for each start symbol") do
+          set_configuration_option(:entry_isolation, true)
+        end
+        options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+          set_configuration_option(:mode, value.to_sym)
+        end
+        add_explain_search_options(options)
+        options.on("--help", "show help") { @options[:help] = true }
+      end
+    end
+
+    # @rbs (OptionParser options) -> void
+    def add_explain_search_options(options)
+      options.on("--counterexample-max-tokens=N", Integer, "maximum counterexample search token budget") do |value|
+        @options[:counterexample_max_tokens] = positive_counterexample_limit(value, "--counterexample-max-tokens")
+      end
+      options.on(
+        "--counterexample-max-configurations=N", Integer, "maximum counterexample search configuration budget"
+      ) do |value|
+        @options[:counterexample_max_configurations] = positive_counterexample_limit(
+          value, "--counterexample-max-configurations"
+        )
+      end
+    end
+
+    # @rbs!
+    #   private def activate_analysis_grammar: (IR::Grammar, ?options: Hash[Symbol, Object?],
+    #     ?explicit_keys: Array[Symbol]) -> IR::Grammar
+  end
+end