ibex 0.1.0 → 0.2.0

data/lib/ibex/rake_task.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "rake/tasklib"
+require_relative "cli"
+
+# @rbs!
+#   module Rake
+#     class TaskLib
+#       def initialize: () -> void
+#     end
+#
+#     class Task
+#       def self.define_task: (Hash[String | Symbol, String | Array[String]]) -> Task
+#                           | (Hash[String | Symbol, String | Array[String]]) {
+#                               (untyped, untyped) -> void
+#                             } -> Task
+#     end
+#
+#     class FileTask < Task
+#     end
+#   end
+
+module Ibex
+  # Declares grammar-to-parser generation in a Rakefile.
+  class RakeTask < Rake::TaskLib
+    attr_accessor :grammar #: String?
+    attr_accessor :output #: String?
+    attr_accessor :options #: Array[String]
+    attr_accessor :action_source #: String | true | nil
+
+    # @rbs (String | Symbol name) ?{ (RakeTask) -> void } -> void
+    def initialize(name, &configuration)
+      super()
+      @name = name
+      @grammar = nil
+      @output = name.to_s.end_with?(".rb") ? name.to_s : nil
+      @options = []
+      @action_source = nil
+      configuration&.call(self)
+      define
+    end
+
+    private
+
+    # @rbs () -> void
+    def define
+      source = @grammar || raise(ArgumentError, "grammar is required")
+      reject_watch_option!
+      target = @output || source.sub(/\.[^.]+\z/, ".rb")
+      target = "#{source}.rb" if target == source
+      prerequisites = grammar_prerequisites(source)
+      action_target = configured_action_source(target)
+      arguments = [*@options]
+      arguments << (@action_source == true ? "--action-source" : "--action-source=#{action_target}") if action_target
+      generate = lambda do |_task, _task_arguments|
+        status = CLI.start([*arguments, "--output-file=#{target}", source])
+        raise "parser generation failed for #{source}" unless status.zero?
+      end
+
+      if action_target
+        Rake::FileTask.define_task(action_target => prerequisites, &generate)
+        Rake::FileTask.define_task(target => [*prerequisites, action_target], &generate)
+      else
+        Rake::FileTask.define_task(target => prerequisites, &generate)
+      end
+
+      Rake::Task.define_task(@name => target) unless @name.to_s == target
+    end
+
+    # @rbs () -> void
+    def reject_watch_option!
+      return unless @options.any? { |option| option == "--watch" || option.start_with?("--watch=") }
+
+      raise ArgumentError, "RakeTask options must not include --watch"
+    end
+
+    # @rbs (String target) -> String?
+    def configured_action_source(target)
+      return nil unless @action_source
+
+      path = @action_source == true ? default_action_source_path(target) : @action_source
+      raise ArgumentError, "action_source must be true or a non-empty String" unless
+        path.is_a?(String) && !path.empty?
+      if File.expand_path(path) == File.expand_path(target)
+        raise ArgumentError, "action_source and output must be distinct"
+      end
+
+      path
+    end
+
+    # @rbs (String target) -> String
+    def default_action_source_path(target)
+      directory = File.dirname(target)
+      basename = File.basename(target)
+      replaced = basename.sub(/\.[^.]+\z/, ".actions.rb")
+      replaced = "#{basename}.actions.rb" if replaced == basename
+      directory == "." ? replaced : File.join(directory, replaced)
+    end
+
+    # @rbs (String source) -> Array[String]
+    def grammar_prerequisites(source)
+      dependencies = Frontend::Resolver.new(source, mode: configured_mode).dependencies
+      [source, *dependencies.drop(1)]
+    end
+
+    # @rbs () -> Symbol
+    def configured_mode
+      explicit = @options.find { |option| option.start_with?("--mode=") }
+      return explicit.delete_prefix("--mode=").to_sym if explicit
+
+      index = @options.index("--mode")
+      index ? @options.fetch(index + 1, "default").to_sym : :default
+    end
+  end
+end

data/lib/ibex/samples.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  # Generates bounded terminal sentences from Grammar IR.
+  class Samples
+    DEFAULT_MAX_EXPANSIONS = 100_000 #: Integer
+
+    # @rbs (IR::Grammar grammar, ?seed: Integer, ?max_tokens: Integer, ?max_depth: Integer,
+    #   ?max_expansions: Integer) -> void
+    def initialize(grammar, seed: 0, max_tokens: 32, max_depth: 16, max_expansions: DEFAULT_MAX_EXPANSIONS)
+      raise ArgumentError, "max_tokens must be positive" unless max_tokens.positive?
+      raise ArgumentError, "max_depth must be positive" unless max_depth.positive?
+      raise ArgumentError, "max_expansions must be positive" unless max_expansions.positive?
+
+      @grammar = grammar
+      @random = Random.new(seed)
+      @max_tokens = max_tokens
+      @max_depth = max_depth
+      @max_expansions = max_expansions
+      @productions = grammar.productions.group_by(&:lhs)
+      @minimum_costs = compute_minimum_costs
+      @minimum_heights = compute_minimum_heights
+    end
+
+    # @rbs (?count: Integer) -> Array[Array[String]]
+    def generate(count: 1)
+      raise ArgumentError, "count must be positive" unless count.positive?
+
+      start = @grammar.symbol(@grammar.start) || raise(Ibex::Error, "(samples):1:1: missing start symbol")
+      minimum = @minimum_costs.fetch(start.id, nil)
+      raise Ibex::Error, "(samples):1:1: start symbol #{@grammar.start} derives no terminal sentence" unless minimum
+
+      if minimum > @max_tokens
+        raise Ibex::Error, "(samples):1:1: minimum sentence needs #{minimum} tokens; limit is #{@max_tokens}"
+      end
+      if count > @max_expansions
+        raise Ibex::Error, "(samples):1:1: count #{count} exceeds expansion limit #{@max_expansions}"
+      end
+
+      remaining_expansions = @max_expansions
+      Array.new(count) do
+        sample, remaining_expansions = expand(start, remaining_expansions)
+        sample
+      end
+    end
+
+    private
+
+    # @rbs () -> Hash[Integer, Integer?]
+    def compute_minimum_costs
+      compute_minimum_values(1) do |production, values|
+        rhs_values = resolved_rhs_values(production, values)
+        rhs_values&.sum
+      end
+    end
+
+    # @rbs () -> Hash[Integer, Integer?]
+    def compute_minimum_heights
+      compute_minimum_values(0) do |production, values|
+        rhs_values = resolved_rhs_values(production, values)
+        rhs_values && ((rhs_values.max || 0) + 1)
+      end
+    end
+
+    # @rbs (Integer terminal_value) { (IR::Production, Hash[Integer, Integer?]) -> Integer? }
+    #   -> Hash[Integer, Integer?]
+    def compute_minimum_values(terminal_value)
+      values = @grammar.symbols.to_h { |symbol| [symbol.id, nil] } #: Hash[Integer, Integer?]
+      dependents = {} #: Hash[Integer, Array[IR::Production]]
+      queue = seed_terminal_values(values, terminal_value)
+
+      @grammar.productions.each do |production|
+        update_minimum(values, queue, production.lhs, yield(production, values)) if production.rhs.empty?
+        production.rhs.uniq.each do |symbol_id|
+          (dependents[symbol_id] ||= []) << production
+        end
+      end
+
+      index = 0
+      while index < queue.length
+        dependents.fetch(queue.fetch(index), []).each do |production|
+          update_minimum(values, queue, production.lhs, yield(production, values))
+        end
+        index += 1
+      end
+
+      values
+    end
+
+    # @rbs (Hash[Integer, Integer?] values, Integer terminal_value) -> Array[Integer]
+    def seed_terminal_values(values, terminal_value)
+      @grammar.symbols.filter_map do |symbol|
+        next unless symbol.terminal? && !symbol.reserved
+
+        values[symbol.id] = terminal_value
+        symbol.id
+      end
+    end
+
+    # @rbs (Hash[Integer, Integer?] values, Array[Integer] queue, Integer symbol_id, Integer? candidate) -> void
+    def update_minimum(values, queue, symbol_id, candidate)
+      return unless candidate
+
+      current = values.fetch(symbol_id)
+      return if current && current <= candidate
+
+      values[symbol_id] = candidate
+      queue << symbol_id
+    end
+
+    # @rbs (IR::Production production, Hash[Integer, Integer?] values) -> Array[Integer]?
+    def resolved_rhs_values(production, values)
+      rhs_values = production.rhs.map { |symbol_id| values.fetch(symbol_id) }
+      return nil if rhs_values.any?(&:nil?)
+
+      rhs_values.compact
+    end
+
+    # @rbs (IR::GrammarSymbol start, Integer remaining_expansions) -> [Array[String], Integer]
+    def expand(start, remaining_expansions)
+      result = [] #: Array[String]
+      work = [[start.id, 0]] #: Array[[Integer, Integer]]
+      pending_minimum = minimum_cost!(start.id)
+
+      while (entry = work.pop)
+        if remaining_expansions.zero?
+          raise Ibex::Error, "(samples):1:1: expansion limit of #{@max_expansions} steps exceeded"
+        end
+
+        remaining_expansions -= 1
+        symbol_id, depth = entry
+        pending_minimum -= minimum_cost!(symbol_id)
+        symbol = @grammar.symbol_by_id(symbol_id) ||
+                 raise(Ibex::Error, "(samples):1:1: missing symbol #{symbol_id}")
+        if symbol.terminal?
+          result << symbol.name
+          next
+        end
+
+        budget = @max_tokens - result.length - pending_minimum
+        production = choose_production(symbol_id, budget, depth)
+        pending_minimum += production_cost(production) ||
+                           raise(Ibex::Error, "(samples):1:1: no bounded derivation for symbol #{symbol_id}")
+        production.rhs.reverse_each { |child_id| work << [child_id, depth + 1] }
+      end
+
+      [result, remaining_expansions]
+    end
+
+    # @rbs (Integer nonterminal_id, Integer budget, Integer depth) -> IR::Production
+    def choose_production(nonterminal_id, budget, depth)
+      productions = @productions[nonterminal_id]
+      raise Ibex::Error, "(samples):1:1: no bounded derivation for symbol #{nonterminal_id}" unless productions
+
+      candidates = productions.select do |production|
+        cost = production_cost(production)
+        cost && cost <= budget
+      end
+      raise Ibex::Error, "(samples):1:1: no bounded derivation for symbol #{nonterminal_id}" if candidates.empty?
+
+      if depth >= @max_depth
+        minimum = candidates.filter_map { |production| production_height(production) }.min
+        candidates = candidates.select { |production| production_height(production) == minimum }
+      end
+      candidates.fetch(@random.rand(candidates.length))
+    end
+
+    # @rbs (Integer symbol_id) -> Integer
+    def minimum_cost!(symbol_id)
+      @minimum_costs.fetch(symbol_id) ||
+        raise(Ibex::Error, "(samples):1:1: no bounded derivation for symbol #{symbol_id}")
+    end
+
+    # @rbs (IR::Production production) -> Integer?
+    def production_cost(production)
+      resolved_rhs_values(production, @minimum_costs)&.sum
+    end
+
+    # @rbs (IR::Production production) -> Integer?
+    def production_height(production)
+      child_heights = resolved_rhs_values(production, @minimum_heights)
+      child_heights && ((child_heights.max || 0) + 1)
+    end
+  end
+end

data/lib/ibex/table_simulation/result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+module Ibex
+  module TableSimulation
+    # Final immutable simulation document.
+    class Result
+      IDENTIFIER = "table-simulation" #: String
+      SCHEMA_VERSION = 1 #: Integer
+
+      attr_reader :grammar_digest #: String
+      attr_reader :algorithm #: String
+      attr_reader :tokens #: Array[String]
+      attr_reader :status #: Symbol
+      attr_reader :steps #: Array[Step]
+
+      # @rbs (grammar_digest: String, algorithm: String, tokens: Array[String], status: Symbol,
+      #   steps: Array[Step]) -> void
+      def initialize(grammar_digest:, algorithm:, tokens:, status:, steps:)
+        raise ArgumentError, "simulation status must be accepted or error" unless %i[accepted error].include?(status)
+
+        @grammar_digest = grammar_digest.dup.freeze
+        @algorithm = algorithm.dup.freeze
+        @tokens = tokens.map { |token| token.dup.freeze }.freeze
+        @status = status
+        @steps = steps.dup.freeze
+        freeze
+      end
+
+      # @rbs () -> Hash[String, untyped]
+      def to_h
+        {
+          "ibex_table_simulation" => IDENTIFIER,
+          "schema_version" => SCHEMA_VERSION,
+          "grammar_digest" => @grammar_digest,
+          "algorithm" => @algorithm,
+          "tokens" => @tokens,
+          "status" => @status.to_s,
+          "steps" => @steps.map(&:to_h)
+        }
+      end
+
+      # @rbs (*untyped) -> String
+      def to_json(*)
+        "#{JSON.pretty_generate(to_h)}\n"
+      end
+    end
+  end
+end

data/lib/ibex/table_simulation/simulator.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "../error"
+
+module Ibex
+  module TableSimulation
+    # Deterministic, semantic-action-free table interpreter.
+    class Simulator
+      DEFAULT_MAX_STEPS = 100_000 #: Integer
+      DEFAULT_MAX_STACK = 10_000 #: Integer
+      EOF_NAME = "$eof" #: String
+      ERROR_NAME = "error" #: String
+      IMPLICIT_ERROR = { type: :error }.freeze #: IR::error_action
+
+      attr_reader :automaton #: IR::Automaton
+      attr_reader :max_steps #: Integer
+      attr_reader :max_stack #: Integer
+      attr_reader :eof #: IR::GrammarSymbol
+
+      # @rbs (IR::Automaton automaton, ?max_steps: Integer, ?max_stack: Integer) -> void
+      def initialize(automaton, max_steps: DEFAULT_MAX_STEPS, max_stack: DEFAULT_MAX_STACK)
+        raise ArgumentError, "max_steps must be positive" unless max_steps.positive?
+        raise ArgumentError, "max_stack must be positive" unless max_stack.positive?
+
+        @automaton = automaton
+        @max_steps = max_steps
+        @max_stack = max_stack
+        @terminals = automaton.grammar.terminals.to_h { |symbol| [symbol.name, symbol] }.freeze
+        @terminal_aliases = terminal_aliases(automaton.grammar.terminals).freeze
+        @eof = @terminals[EOF_NAME] || raise(Ibex::Error, "(debug):1:1: automaton has no $eof terminal")
+      end
+
+      # @rbs () -> Session
+      def start
+        Session.new(self)
+      end
+
+      # @rbs (Array[String] tokens) -> Result
+      def simulate(tokens)
+        session = start
+        tokens.each do |token|
+          session.push(token)
+          break if session.status
+        end
+        session.finish
+      end
+
+      # @rbs (String spelling) -> IR::GrammarSymbol
+      def terminal(spelling)
+        if [EOF_NAME, ERROR_NAME].include?(spelling)
+          raise Ibex::Error, "(debug):1:1: reserved terminal #{spelling.inspect} cannot be supplied"
+        end
+
+        terminal = @terminals[spelling]
+        return terminal if terminal
+
+        empty = [] #: Array[IR::GrammarSymbol]
+        aliases = @terminal_aliases.fetch(spelling, empty)
+        return aliases.first if aliases.length == 1
+
+        if aliases.length > 1
+          names = aliases.map(&:name).sort.join(", ")
+          raise Ibex::Error, "(debug):1:1: terminal display name #{spelling.inspect} is ambiguous: #{names}"
+        end
+
+        raise Ibex::Error, "(debug):1:1: unknown terminal #{spelling.inspect}"
+      end
+
+      private
+
+      # @rbs (Array[IR::GrammarSymbol] terminals) -> Hash[String, Array[IR::GrammarSymbol]]
+      def terminal_aliases(terminals)
+        aliases = Hash.new { |hash, key| hash[key] = [] } #: Hash[String, Array[IR::GrammarSymbol]]
+        terminals.each do |terminal|
+          aliases[terminal.display_name] << terminal if terminal.display_name
+        end
+        aliases.each_value(&:freeze)
+        aliases
+      end
+    end
+
+    # Stateful token-at-a-time table simulation session.
+    class Session
+      # @rbs @steps: Array[Step]
+      # @rbs @tokens: Array[String]
+
+      attr_reader :status #: Symbol?
+
+      # @rbs (Simulator simulator) -> void
+      def initialize(simulator)
+        @simulator = simulator
+        @state_stack = [0] #: Array[Integer]
+        @status = nil
+        @steps = []
+        @tokens = []
+        @finished = false
+      end
+
+      # @rbs (String spelling) -> Array[Step]
+      def push(spelling)
+        ensure_active!
+        terminal = @simulator.terminal(spelling)
+        @tokens << terminal.name
+        process(terminal, eof: false)
+      end
+
+      # @rbs () -> Array[Step]
+      def steps = @steps.dup.freeze
+
+      # @rbs () -> Array[String]
+      def tokens = @tokens.dup.freeze
+
+      # @rbs () -> Result
+      def finish
+        raise Ibex::Error, "(debug):1:1: simulation session is already finished" if @finished
+
+        @finished = true
+        process(@simulator.eof, eof: true) until @status
+        Result.new(
+          grammar_digest: @simulator.automaton.grammar_digest,
+          algorithm: @simulator.automaton.algorithm,
+          tokens: @tokens,
+          status: @status || raise(Ibex::Error, "(debug):1:1: simulation did not terminate"),
+          steps: @steps
+        )
+      end
+
+      private
+
+      # @rbs (IR::GrammarSymbol terminal, eof: bool) -> Array[Step]
+      def process(terminal, eof:)
+        first = @steps.length
+        loop do
+          state = current_state
+          action, source = action_for(state, terminal.id)
+          case action.fetch(:type)
+          when :shift
+            record_shift(state, terminal, action, source)
+            next if eof
+
+            break
+          when :reduce then record_reduce(state, terminal, action, source)
+          when :accept
+            record_terminal(state, terminal, "accept", source)
+            @status = :accepted
+            break
+          when :error
+            record_terminal(state, terminal, "error", source)
+            @status = :error
+            break
+          else raise Ibex::Error, "(debug):1:1: unknown table action #{action.inspect}"
+          end
+        end
+        @steps.drop(first).freeze
+      end
+
+      # @rbs (IR::AutomatonState state, Integer token_id) -> [IR::parser_action, String]
+      def action_for(state, token_id)
+        return [state.actions.fetch(token_id), "explicit"] if state.actions.key?(token_id)
+        return [state.default_action, "default"] if state.default_action
+
+        [Simulator::IMPLICIT_ERROR, "implicit"]
+      end
+
+      # @rbs (IR::AutomatonState state, IR::GrammarSymbol terminal, IR::parser_action action, String source) -> void
+      def record_shift(state, terminal, action, source)
+        shift = action #: IR::shift_action
+        before = @state_stack.length
+        target = shift.fetch(:state)
+        @state_stack << target
+        enforce_stack_budget!
+        append_step(state, terminal, "shift", source, target_state: target, before: before)
+      end
+
+      # @rbs (IR::AutomatonState state, IR::GrammarSymbol terminal, IR::parser_action action, String source) -> void
+      def record_reduce(state, terminal, action, source)
+        reduction = action #: IR::reduce_action
+        production_id = reduction.fetch(:production)
+        production = @simulator.automaton.grammar.productions.fetch(production_id)
+        length = production.rhs.length
+        before = @state_stack.length
+        if length >= before
+          raise Ibex::Error, "(debug):1:1: production #{production_id} underflows the simulated state stack"
+        end
+
+        @state_stack.pop(length)
+        goto = current_state.gotos[production.lhs]
+        unless goto
+          raise Ibex::Error, "(debug):1:1: missing goto for production #{production_id} from state #{current_state.id}"
+        end
+
+        @state_stack << goto
+        enforce_stack_budget!
+        lhs = @simulator.automaton.grammar.symbol_by_id(production.lhs)
+        raise Ibex::Error, "(debug):1:1: missing lhs symbol #{production.lhs}" unless lhs
+
+        append_step(
+          state, terminal, "reduce", source,
+          production_id: production_id, lhs: lhs.name, rhs_length: length,
+          target_state: goto, before: before
+        )
+      end
+
+      # @rbs (IR::AutomatonState state, IR::GrammarSymbol terminal, String action, String source) -> void
+      def record_terminal(state, terminal, action, source)
+        append_step(state, terminal, action, source, before: @state_stack.length)
+      end
+
+      # @rbs (IR::AutomatonState state, IR::GrammarSymbol terminal, String action, String source,
+      #   before: Integer, ?production_id: Integer?, ?lhs: String?, ?rhs_length: Integer?,
+      #   ?target_state: Integer?) -> void
+      def append_step(state, terminal, action, source, before:, production_id: nil, lhs: nil, rhs_length: nil,
+                      target_state: nil)
+        raise Ibex::Error, "(debug):1:1: simulation exceeded #{@simulator.max_steps} actions" \
+          if @steps.length >= @simulator.max_steps
+
+        @steps << Step.new(
+          sequence: @steps.length + 1,
+          state: state.id,
+          token_id: terminal.id,
+          token: terminal.display_name || terminal.name,
+          action: action,
+          action_source: source,
+          production_id: production_id,
+          lhs: lhs,
+          rhs_length: rhs_length,
+          target_state: target_state,
+          stack_depth_before: before,
+          stack_depth_after: @state_stack.length
+        )
+      end
+
+      # @rbs () -> IR::AutomatonState
+      def current_state
+        id = @state_stack.last || raise(Ibex::Error, "(debug):1:1: simulated state stack is empty")
+        @simulator.automaton.states.fetch(id)
+      end
+
+      # @rbs () -> void
+      def enforce_stack_budget!
+        return if @state_stack.length <= @simulator.max_stack
+
+        raise Ibex::Error, "(debug):1:1: simulation exceeded stack depth #{@simulator.max_stack}"
+      end
+
+      # @rbs () -> void
+      def ensure_active!
+        raise Ibex::Error, "(debug):1:1: simulation session is already finished" if @finished || @status
+      end
+    end
+  end
+end

data/lib/ibex/table_simulation/step.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module TableSimulation
+    # One immutable parser-table action.
+    class Step
+      attr_reader :sequence #: Integer
+      attr_reader :state #: Integer
+      attr_reader :token_id #: Integer
+      attr_reader :token #: String
+      attr_reader :action #: String
+      attr_reader :action_source #: String
+      attr_reader :production_id #: Integer?
+      attr_reader :lhs #: String?
+      attr_reader :rhs_length #: Integer?
+      attr_reader :target_state #: Integer?
+      attr_reader :stack_depth_before #: Integer
+      attr_reader :stack_depth_after #: Integer
+
+      # @rbs (sequence: Integer, state: Integer, token_id: Integer, token: String, action: String,
+      #   action_source: String, production_id: Integer?, lhs: String?, rhs_length: Integer?,
+      #   target_state: Integer?, stack_depth_before: Integer, stack_depth_after: Integer) -> void
+      def initialize(sequence:, state:, token_id:, token:, action:, action_source:, production_id:, lhs:, rhs_length:,
+                     target_state:, stack_depth_before:, stack_depth_after:)
+        @sequence = sequence
+        @state = state
+        @token_id = token_id
+        @token = token.dup.freeze
+        @action = action.dup.freeze
+        @action_source = action_source.dup.freeze
+        @production_id = production_id
+        @lhs = lhs&.dup&.freeze
+        @rhs_length = rhs_length
+        @target_state = target_state
+        @stack_depth_before = stack_depth_before
+        @stack_depth_after = stack_depth_after
+        freeze
+      end
+
+      # @rbs () -> Hash[String, untyped]
+      def to_h
+        {
+          "sequence" => @sequence,
+          "state" => @state,
+          "token_id" => @token_id,
+          "token" => @token,
+          "action" => @action,
+          "action_source" => @action_source,
+          "production_id" => @production_id,
+          "lhs" => @lhs,
+          "rhs_length" => @rhs_length,
+          "target_state" => @target_state,
+          "stack_depth_before" => @stack_depth_before,
+          "stack_depth_after" => @stack_depth_after
+        }.freeze
+      end
+    end
+  end
+end

data/lib/ibex/table_simulation/text.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module TableSimulation
+    # Stable one-line renderer for simulation steps.
+    module Text
+      class << self
+        # @rbs (Step step) -> String
+        def render_step(step)
+          detail = case step.action
+                   when "shift" then " target=#{step.target_state}"
+                   when "reduce"
+                     " production=#{step.production_id} lhs=#{step.lhs} rhs=#{step.rhs_length} " \
+                     "goto=#{step.target_state}"
+                   else ""
+                   end
+          "#{step.sequence}: state=#{step.state} token=#{step.token.inspect} action=#{step.action}" \
+            "#{detail} source=#{step.action_source} stack=#{step.stack_depth_before}->#{step.stack_depth_after}"
+        end
+
+        # @rbs (Result result) -> String
+        def render(result)
+          lines = result.steps.map { |step| render_step(step) }
+          lines << "status=#{result.status}"
+          "#{lines.join("\n")}\n"
+        end
+      end
+    end
+  end
+end