ibex 0.1.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/counterexample_options.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../lalr/conflict_search_limits"
+
 module Ibex
   # Counterexample report limits and their command-line validation.
   module CLICounterexampleOptions
+    # @rbs @options: cli_options
+
     DEFAULTS = {
-      counterexample_max_tokens: LALR::Counterexample::DEFAULT_MAX_TOKENS,
-      counterexample_max_configurations: LALR::Counterexample::DEFAULT_MAX_CONFIGURATIONS
+      counterexample_max_tokens: LALR::ConflictSearchLimits::DEFAULT_MAX_TOKENS,
+      counterexample_max_configurations: LALR::ConflictSearchLimits::DEFAULT_MAX_CONFIGURATIONS
     }.freeze #: Hash[Symbol, Integer]
 
     private

data/lib/ibex/cli/coverage.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "tempfile"
+require_relative "../coverage"
+
+module Ibex
+  # CLI collection, merge, and threshold checks for runtime coverage.
+  module CLICoverage
+    # @rbs!
+    #   private def same_file_target?: (String left, String right) -> bool
+    #
+    #   type coverage_output_options = {
+    #     paths: Array[String],
+    #     ?output: String
+    #   }
+    #   type coverage_check_options = {
+    #     paths: Array[String],
+    #     min_states: Float,
+    #     min_productions: Float
+    #   }
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_command(arguments)
+      operation = arguments.shift
+      case operation
+      when "collect" then run_coverage_collect(arguments)
+      when "merge" then run_coverage_merge(arguments)
+      when "check" then run_coverage_check(arguments)
+      else
+        raise Ibex::Error, "(cli):1:1: coverage requires collect, merge, or check"
+      end
+    end
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_collect(arguments)
+      settings = coverage_output_options(arguments, "collect", "INPUT")
+      input = single_coverage_path(settings.fetch(:paths), "coverage collect")
+      reject_coverage_output_collision([input], settings[:output])
+      report = Coverage::Collector.collect_file(input)
+      write_coverage_report(report, settings[:output])
+      0
+    end
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_merge(arguments)
+      settings = coverage_output_options(arguments, "merge", "INPUT...")
+      inputs = settings.fetch(:paths)
+      raise Ibex::Error, "(cli):1:1: coverage merge requires at least one input" if inputs.empty?
+
+      reject_coverage_output_collision(inputs, settings[:output])
+      reports = inputs.map { |path| Coverage::Report.load_file(path) }
+      report = Coverage::Report.merge(reports)
+      write_coverage_report(report, settings[:output])
+      0
+    rescue ArgumentError => e
+      raise Ibex::Error, "(coverage):1:1: #{e.message}"
+    end
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_check(arguments)
+      settings = coverage_check_options(arguments)
+      path = single_coverage_path(settings.fetch(:paths), "coverage check")
+      report = Coverage::Report.load_file(path)
+      state_percentage = coverage_percentage(report.state_hits.length, report.state_count)
+      production_percentage = coverage_percentage(report.production_hits.length, report.production_count)
+      passed = state_percentage >= settings.fetch(:min_states) &&
+               production_percentage >= settings.fetch(:min_productions)
+      summary = format(
+        "coverage %<status>s: states %<states>.2f%% (%<state_hits>d/%<state_total>d), " \
+        "productions %<productions>.2f%% (%<production_hits>d/%<production_total>d)",
+        status: passed ? "ok" : "failed",
+        states: state_percentage,
+        state_hits: report.state_hits.length,
+        state_total: report.state_count,
+        productions: production_percentage,
+        production_hits: report.production_hits.length,
+        production_total: report.production_count
+      )
+      (passed ? @stdout : @stderr).puts(summary)
+      passed ? 0 : 1
+    end
+
+    # @rbs (Array[String] arguments, String command, String operands) -> coverage_output_options
+    def coverage_output_options(arguments, command, operands)
+      settings = { paths: [] } #: coverage_output_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex coverage #{command} #{operands} [-o FILE]"
+        options.on("-o FILE", "--output=FILE", "write atomically to FILE") { |value| settings[:output] = value }
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings
+    end
+
+    # @rbs (Array[String] arguments) -> coverage_check_options
+    def coverage_check_options(arguments)
+      settings = { paths: [], min_states: 0.0, min_productions: 0.0 } #: coverage_check_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex coverage check REPORT [thresholds]"
+        options.on("--min-states=PERCENT", Float, "minimum visited states") do |value|
+          settings[:min_states] = coverage_threshold(value, "min-states")
+        end
+        options.on("--min-productions=PERCENT", Float, "minimum reduced productions") do |value|
+          settings[:min_productions] = coverage_threshold(value, "min-productions")
+        end
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings
+    end
+
+    # @rbs (Float value, String name) -> Float
+    def coverage_threshold(value, name)
+      return value if value.finite? && value >= 0.0 && value <= 100.0
+
+      raise OptionParser::InvalidArgument, "--#{name} must be between 0 and 100"
+    end
+
+    # @rbs (Integer covered, Integer total) -> Float
+    def coverage_percentage(covered, total)
+      return 100.0 if total.zero?
+
+      covered.fdiv(total) * 100.0
+    end
+
+    # @rbs (Array[String] arguments, String command) -> String
+    def single_coverage_path(arguments, command)
+      return arguments.first if arguments.length == 1
+
+      raise Ibex::Error, "(cli):1:1: #{command} requires exactly one input"
+    end
+
+    # @rbs (Array[String] inputs, String? output) -> void
+    def reject_coverage_output_collision(inputs, output)
+      return unless output
+      return unless inputs.any? { |input| same_file_target?(input, output) }
+
+      raise Ibex::Error, "(cli):1:1: coverage input and output paths must be distinct"
+    end
+
+    # @rbs (Coverage::Report report, String? output) -> void
+    def write_coverage_report(report, output)
+      source = report.to_json
+      return @stdout.write(source) unless output
+
+      atomic_write_coverage(output, source)
+    end
+
+    # @rbs (String path, String source) -> void
+    def atomic_write_coverage(path, source)
+      target_path = File.symlink?(path) ? File.realpath(path) : path
+      directory = File.dirname(File.expand_path(target_path))
+      basename = File.basename(target_path)
+      Tempfile.create([".#{basename}.", ".tmp"], directory) do |temporary|
+        temporary.binmode
+        temporary.write(source)
+        temporary.flush
+        temporary.fsync
+        temporary.chmod(coverage_file_mode(target_path))
+        temporary.close
+        File.rename(temporary.path, target_path)
+      end
+    end
+
+    # @rbs (String path) -> Integer
+    def coverage_file_mode(path)
+      return File.stat(path).mode & 0o777 if File.exist?(path)
+
+      0o666 & ~File.umask
+    end
+  end
+end

data/lib/ibex/cli/debug.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "optparse"
+require_relative "../table_simulation"
+
+module Ibex
+  # Safe parser-table simulation subcommand.
+  module CLIDebug
+    # @rbs!
+    #   type debug_options = {
+    #     paths: Array[String],
+    #     format: String,
+    #     max_steps: Integer,
+    #     max_stack: Integer
+    #   }
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_debug_command(arguments)
+      settings = debug_options(arguments)
+      operands = settings.fetch(:paths)
+      raise Ibex::Error, "(cli):1:1: debug requires an Automaton IR file" if operands.empty?
+
+      path = operands.first
+      value = IR::Validator.validate(File.read(path))
+      raise Ibex::Error, "#{path}:1:1: debug requires Automaton IR" unless value.is_a?(IR::Automaton)
+
+      simulator = TableSimulation::Simulator.new(
+        value,
+        max_steps: settings.fetch(:max_steps),
+        max_stack: settings.fetch(:max_stack)
+      )
+      tokens = operands.drop(1)
+      interactive = tokens.empty?
+      format = settings.fetch(:format)
+      result = interactive ? simulate_debug_input(simulator, format) : simulator.simulate(tokens)
+      write_debug_result(result, format, steps_written: interactive && format == "text")
+      result.status == :accepted ? 0 : 1
+    rescue ArgumentError => e
+      raise Ibex::Error, "(debug):1:1: #{e.message}"
+    end
+
+    # @rbs (Array[String] arguments) -> debug_options
+    def debug_options(arguments)
+      settings = {
+        paths: [],
+        format: "text",
+        max_steps: TableSimulation::Simulator::DEFAULT_MAX_STEPS,
+        max_stack: TableSimulation::Simulator::DEFAULT_MAX_STACK
+      } #: debug_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex debug AUTOMATON.json [TOKEN...]"
+        options.on("--format=FORMAT", %w[text json], "text or json") { |value| settings[:format] = value }
+        options.on("--max-steps=N", Integer, "maximum simulated actions") do |value|
+          settings[:max_steps] = positive_debug_budget(value, "max-steps")
+        end
+        options.on("--max-stack=N", Integer, "maximum simulated state stack depth") do |value|
+          settings[:max_stack] = positive_debug_budget(value, "max-stack")
+        end
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings
+    end
+
+    # @rbs (Integer value, String name) -> Integer
+    def positive_debug_budget(value, name)
+      return value if value.positive?
+
+      raise OptionParser::InvalidArgument, "--#{name} must be positive"
+    end
+
+    # @rbs (TableSimulation::Simulator simulator, String format) -> TableSimulation::Result
+    def simulate_debug_input(simulator, format)
+      session = simulator.start
+      while (line = @stdin.gets)
+        spelling = line.strip
+        break if spelling.empty?
+
+        steps = session.push(spelling)
+        write_debug_steps(steps) if format == "text"
+        break if session.status
+      end
+      written = session.steps.length
+      result = session.finish
+      write_debug_steps(result.steps.drop(written)) if format == "text"
+      result
+    end
+
+    # @rbs (TableSimulation::Result result, String format, steps_written: bool) -> void
+    def write_debug_result(result, format, steps_written:)
+      if format == "json"
+        @stdout.write(result.to_json)
+      else
+        write_debug_steps(result.steps) unless steps_written
+        @stdout.puts("status=#{result.status}")
+      end
+    end
+
+    # @rbs (Array[TableSimulation::Step] steps) -> void
+    def write_debug_steps(steps)
+      steps.each { |step| @stdout.puts(TableSimulation::Text.render_step(step)) }
+    end
+  end
+end