ibex 0.1.0 → 0.2.0

data/lib/ibex/codegen/cst_metadata.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Codegen
+    # Builds the deterministic kind space embedded in CST-aware parser tables.
+    class CSTMetadata
+      # @rbs!
+      #   type kind_map = Hash[String, Integer]
+      #   type kinds = {
+      #     names: Array[String],
+      #     terminal_range: Array[Integer],
+      #     nonterminal_range: Array[Integer],
+      #     named: kind_map,
+      #     named_nonterminals: Hash[Integer, Integer],
+      #     trivia: kind_map,
+      #     synthetic: kind_map
+      #   }
+      #   type field_slot = Integer | { index: Integer, extraction: Symbol }
+      #   type slot = { node_kind: Integer, node_name: String, fields: Hash[String, field_slot] }
+      #   type metadata = {
+      #     version: Integer,
+      #     trivia_policy: Symbol,
+      #     kinds: kinds,
+      #     slots: Hash[Integer, slot]
+      #   }
+
+      TRIVIA_KINDS = %w[
+        whitespace
+        newline
+        line_comment
+        block_comment
+        custom_skip
+        skipped_tokens
+      ].freeze #: Array[String]
+
+      SYNTHETIC_KINDS = %w[
+        lexical_error_token
+        missing_token
+        error_node
+        source_file
+        synthetic_root
+      ].freeze #: Array[String]
+
+      # @rbs @grammar: IR::Grammar
+      # @rbs @trivia_policy: Symbol
+
+      # @rbs (IR::Grammar grammar, ?trivia_policy: Symbol | String) -> void
+      def initialize(grammar, trivia_policy: :leading)
+        @grammar = grammar
+        @trivia_policy = normalize_trivia_policy(trivia_policy)
+      end
+
+      # Return table-ready CST metadata with stable insertion order.
+      # @rbs () -> metadata
+      def build
+        names = @grammar.symbols.sort_by(&:id).map(&:name)
+        named = append_named_kinds(names)
+        trivia = append_kinds(names, TRIVIA_KINDS)
+        synthetic = append_kinds(names, SYNTHETIC_KINDS)
+        terminals = @grammar.terminals.map(&:id)
+        nonterminals = @grammar.nonterminals.map(&:id)
+        kinds = {
+          names: names.freeze,
+          terminal_range: half_open_range(terminals),
+          nonterminal_range: half_open_range(nonterminals),
+          named: named.freeze,
+          named_nonterminals: named_nonterminals(named).freeze,
+          trivia: trivia.freeze,
+          synthetic: synthetic.freeze
+        }.freeze #: kinds
+        metadata = { # rubocop:disable Style/RedundantAssignment -- preserves the exact record type for Steep.
+          version: 1, trivia_policy: @trivia_policy,
+          kinds: kinds, slots: slot_metadata(named).freeze
+        }.freeze #: metadata
+        metadata
+      end
+
+      private
+
+      # @rbs (Symbol | String policy) -> Symbol
+      def normalize_trivia_policy(policy)
+        normalized = policy.to_sym
+        normalized = :leading if normalized == :attach
+        return normalized if %i[leading balanced drop].include?(normalized)
+
+        raise ArgumentError, "cst_trivia must be :leading, :balanced, or :drop"
+      end
+
+      # @rbs (Array[String] names) -> Hash[String, Integer]
+      def append_named_kinds(names)
+        node_names = @grammar.productions.filter_map { |production| production.node&.fetch(:name) }.uniq.sort
+        append_kinds(names, node_names)
+      end
+
+      # @rbs (Array[String] names, Array[String] additions) -> Hash[String, Integer]
+      def append_kinds(names, additions)
+        additions.to_h do |name|
+          kind = names.length
+          names << name.freeze
+          [name.freeze, kind]
+        end
+      end
+
+      # @rbs (Array[Integer] ids) -> Array[Integer]
+      def half_open_range(ids)
+        return [0, 0].freeze if ids.empty?
+
+        [ids.min, ids.max + 1].freeze
+      end
+
+      # @rbs (Hash[String, Integer] named) -> Hash[Integer, Integer]
+      def named_nonterminals(named)
+        result = {} #: Hash[Integer, Integer]
+        @grammar.productions.each do |production|
+          node = production.node
+          next unless node
+
+          kind = named.fetch(node.fetch(:name))
+          current = result[kind]
+          if current && current != production.lhs
+            raise ArgumentError, "@node #{node.fetch(:name)} spans multiple nonterminals"
+          end
+
+          result[kind] = production.lhs
+        end
+        result
+      end
+
+      # @rbs (Hash[String, Integer] named) -> Hash[Integer, slot]
+      def slot_metadata(named)
+        @grammar.productions.filter_map do |production|
+          node = production.node
+          next unless node
+
+          fields = node.fetch(:fields).each_with_index.to_h do |name, index|
+            [name, field_slot(index, production.rhs.fetch(index))]
+          end.freeze
+          [
+            production.id,
+            {
+              node_kind: named.fetch(node.fetch(:name)),
+              node_name: node.fetch(:name),
+              fields: fields
+            }.freeze
+          ]
+        end.to_h
+      end
+
+      # @rbs (Integer index, Integer symbol_id) -> field_slot
+      def field_slot(index, symbol_id)
+        extraction = repetition_extraction(symbol_id)
+        return index unless extraction
+
+        value = { index: index, extraction: extraction } #: field_slot
+        value.freeze
+      end
+
+      # @rbs (Integer symbol_id) -> Symbol?
+      def repetition_extraction(symbol_id)
+        origins = @grammar.productions
+                          .select { |production| production.lhs == symbol_id }
+                          .map { |production| production.origin.fetch(:kind) }.uniq
+        return :separated_list if origins == [:separated_list_expansion]
+        return :repetition if (origins - %i[star_expansion plus_expansion]).empty? && !origins.empty?
+
+        nil
+      end
+    end
+  end
+end

data/lib/ibex/codegen/documentation.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "railroad"
+require_relative "symbol_labels"
+
+module Ibex
+  module Codegen
+    # Renders normalized user rules as deterministic Markdown, HTML, or railroad SVG.
+    module Documentation
+      FORMATS = %w[markdown html railroad].freeze #: Array[String]
+
+      class << self
+        # @rbs (IR::Grammar grammar, format: String | Symbol) -> String
+        def render(grammar, format:)
+          case format.to_s
+          when "markdown" then render_markdown(grammar)
+          when "html" then render_html(grammar)
+          when "railroad" then Railroad.render(grammar)
+          else raise ArgumentError, "unsupported documentation format #{format.inspect}"
+          end
+        end
+
+        private
+
+        # @rbs (IR::Grammar grammar) -> String
+        def render_markdown(grammar)
+          labels = SymbolLabels.build(grammar)
+          lines = ["# #{markdown_escape(grammar.class_name)} grammar", ""]
+          rule_groups(grammar).each do |symbol, productions|
+            lines << "## #{markdown_code(labels.fetch(symbol.id))}"
+            lines << ""
+            append_markdown_documentation(lines, symbol.documentation)
+            lines << "Alternatives:"
+            lines << ""
+            productions.each do |production|
+              lines << "- #{markdown_alternative(grammar, production, labels)}"
+            end
+            lines << ""
+          end
+          "#{lines.join("\n").rstrip}\n"
+        end
+
+        # @rbs (Array[String] lines, String? documentation) -> void
+        def append_markdown_documentation(lines, documentation)
+          return unless documentation
+
+          documentation.split("\n", -1).each do |line|
+            escaped = markdown_escape(line)
+            lines << (escaped.empty? ? ">" : "> #{escaped}")
+          end
+          lines << ""
+        end
+
+        # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels) -> String
+        def markdown_alternative(grammar, production, labels)
+          return "ε" if production.rhs.empty?
+
+          production.rhs.map do |symbol_id|
+            raise Ibex::Error, "missing grammar symbol id #{symbol_id}" unless grammar.symbol_by_id(symbol_id)
+
+            markdown_code(labels.fetch(symbol_id))
+          end.join(" ")
+        end
+
+        # @rbs (IR::Grammar grammar) -> String
+        def render_html(grammar)
+          labels = SymbolLabels.build(grammar)
+          title = "#{html_escape(grammar.class_name)} grammar"
+          lines = html_start(title)
+          rule_groups(grammar).each do |symbol, productions|
+            append_html_rule(lines, grammar, symbol, productions, labels)
+          end
+          lines.push("  </main>", "</body>", "</html>")
+          "#{lines.join("\n")}\n"
+        end
+
+        # @rbs (String title) -> Array[String]
+        def html_start(title)
+          [
+            "<!doctype html>",
+            "<html lang=\"en\">",
+            "<head>",
+            "  <meta charset=\"utf-8\">",
+            "  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
+            "  <title>#{title}</title>",
+            "  <style>",
+            "    body { color: #172033; background: #fff; font: 16px/1.6 system-ui, sans-serif; margin: 0; }",
+            "    main { max-width: 72rem; margin: 0 auto; padding: 2rem; }",
+            "    section { border-top: 1px solid #d8dee9; padding: 1.25rem 0; }",
+            "    code { background: #f3f6fa; border-radius: .25rem; padding: .1rem .3rem; }",
+            "    .documentation { white-space: normal; }",
+            "    .alternatives { padding-left: 1.5rem; }",
+            "  </style>",
+            "</head>",
+            "<body>",
+            "  <main>",
+            "    <h1>#{title}</h1>"
+          ]
+        end
+
+        # @rbs (Array[String] lines, IR::Grammar grammar, IR::GrammarSymbol symbol,
+        #   Array[IR::Production] productions, Hash[Integer, String] labels) -> void
+        def append_html_rule(lines, grammar, symbol, productions, labels)
+          label = html_escape(labels.fetch(symbol.id))
+          lines << "    <section aria-labelledby=\"rule-#{symbol.id}\">"
+          lines << "      <h2 id=\"rule-#{symbol.id}\"><code>#{label}</code></h2>"
+          if symbol.documentation
+            documentation = symbol.documentation.split("\n", -1).map { |line| html_escape(line) }.join("<br>\n        ")
+            lines << "      <p class=\"documentation\">#{documentation}</p>"
+          end
+          lines << "      <ol class=\"alternatives\" aria-label=\"Alternatives for #{label}\">"
+          productions.each do |production|
+            lines << "        <li>#{html_alternative(grammar, production, labels)}</li>"
+          end
+          lines << "      </ol>"
+          lines << "    </section>"
+        end
+
+        # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels) -> String
+        def html_alternative(grammar, production, labels)
+          return "<span aria-label=\"empty\">ε</span>" if production.rhs.empty?
+
+          production.rhs.map do |symbol_id|
+            raise Ibex::Error, "missing grammar symbol id #{symbol_id}" unless grammar.symbol_by_id(symbol_id)
+
+            "<code>#{html_escape(labels.fetch(symbol_id))}</code>"
+          end.join(" ")
+        end
+
+        # @rbs (IR::Grammar grammar) -> Array[[IR::GrammarSymbol, Array[IR::Production]]]
+        def rule_groups(grammar)
+          grouped = grammar.productions.select { |production| production.origin[:kind].to_s == "user" }.group_by(&:lhs)
+          grammar.nonterminals.filter_map do |symbol|
+            productions = grouped[symbol.id]
+            [symbol, productions] if productions
+          end
+        end
+
+        # @rbs (String value) -> String
+        def markdown_code(value)
+          safe = html_escape(value)
+          longest_run = safe.scan(/`+/).map(&:length).max.to_i
+          delimiter = "`" * (longest_run + 1)
+          padding = markdown_code_padding?(safe) ? " " : ""
+          "#{delimiter}#{padding}#{safe}#{padding}#{delimiter}"
+        end
+
+        # @rbs (String value) -> bool
+        def markdown_code_padding?(value)
+          return true if value.start_with?("`") || value.end_with?("`")
+
+          value.start_with?(" ") && value.end_with?(" ") && !value.match?(/\A +\z/)
+        end
+
+        # @rbs (String value) -> String
+        def markdown_escape(value)
+          html_escape(value).gsub(/([\\`*_{}\[\]()#+\-.!|>])/) { |match| "\\#{match}" }
+        end
+
+        # @rbs (String value) -> String
+        def html_escape(value)
+          safe = value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+                      .gsub(/[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/u, "\uFFFD")
+          safe.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+              .gsub('"', "&quot;").gsub("'", "&#39;")
+        end
+      end
+    end
+  end
+end

data/lib/ibex/codegen/explain.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require_relative "../lalr"
+require_relative "symbol_labels"
+
+module Ibex
+  module Codegen
+    # @rbs!
+    #   type explain_selection = {
+    #     state: IR::AutomatonState,
+    #     conflict: IR::conflict,
+    #     conflict_index: Integer
+    #   }
+    #
+    #   type explain_entry = {
+    #     state: IR::AutomatonState,
+    #     conflict: IR::conflict,
+    #     example: IR::counterexample
+    #   }
+
+    # Renders a selected conflict explanation from Automaton IR and counterexamples.
+    # rubocop:disable Metrics/ClassLength -- inline contracts and two stable output formats stay near selection policy.
+    class Explain
+      SCHEMA_VERSION = 1 #: Integer
+
+      # @rbs (IR::Automaton automaton, ?state: Integer?, ?token: String?, ?max_tokens: Integer,
+      #   ?max_configurations: Integer) -> void
+      def initialize(automaton, state: nil, token: nil, max_tokens: LALR::Counterexample::DEFAULT_MAX_TOKENS,
+                     max_configurations: LALR::Counterexample::DEFAULT_MAX_CONFIGURATIONS)
+        @automaton = automaton
+        @grammar = automaton.grammar
+        @state_selector = state
+        @token_query = token
+        @max_tokens = max_tokens
+        @max_configurations = max_configurations
+        @labels = SymbolLabels.build(@grammar)
+        @token_selector = resolve_token(token)
+        validate_state!
+        @entries = select_entries
+      end
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def to_h
+        unifying = @entries.count { |entry| entry.fetch(:example).fetch(:unifying) }
+        {
+          ibex_explain: "conflicts",
+          schema_version: SCHEMA_VERSION,
+          algorithm: @automaton.algorithm,
+          selectors: {
+            state: @state_selector,
+            token: @token_selector && token_reference(@token_selector, query: @token_query)
+          },
+          search: { max_tokens: @max_tokens, max_configurations: @max_configurations },
+          summary: {
+            matched_conflicts: @entries.length,
+            unifying_counterexamples: unifying,
+            nonunifying_witnesses: @entries.length - unifying
+          },
+          conflicts: @entries.map { |entry| conflict_document(entry) }
+        }
+      end
+
+      # @rbs () -> String
+      def render_text
+        lines = [
+          "Ibex conflict explanation v#{SCHEMA_VERSION}",
+          "Algorithm: #{@automaton.algorithm}",
+          "State selector: #{@state_selector || 'all'}",
+          "Token selector: #{@token_selector ? token_label(@token_selector, query: @token_query) : 'all'}",
+          "Search budget: #{@max_tokens} tokens, #{@max_configurations} configurations",
+          "Matched conflicts: #{@entries.length}",
+          ""
+        ]
+        if @entries.empty?
+          lines << "No conflicts matched the selectors."
+        else
+          @entries.each_with_index { |entry, index| append_conflict(lines, entry, index + 1) }
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      # @rbs (String? query) -> IR::GrammarSymbol?
+      def resolve_token(query)
+        return unless query
+
+        canonical = @grammar.terminals.find { |symbol| symbol.name == query }
+        return canonical if canonical
+
+        displayed = @grammar.terminals.select { |symbol| symbol.display_name == query }
+        return displayed.first if displayed.one?
+
+        if displayed.length > 1
+          names = displayed.map(&:name).sort.join(", ")
+          raise Ibex::Error, "(cli):1:1: token display name #{query.inspect} is ambiguous; use one of: #{names}"
+        end
+
+        raise Ibex::Error,
+              "(cli):1:1: unknown token #{query.inspect}; use a grammar token name or an exact display name"
+      end
+
+      # @rbs () -> void
+      def validate_state!
+        return unless @state_selector
+        return if @state_selector >= 0 && @automaton.states.any? { |state| state.id == @state_selector }
+
+        raise Ibex::Error, "(cli):1:1: unknown automaton state #{@state_selector}"
+      end
+
+      # @rbs () -> Array[explain_entry]
+      def select_entries
+        selections = selected_conflicts
+        return [] if selections.empty?
+
+        counterexamples = LALR::Counterexample.new(
+          @automaton, max_tokens: @max_tokens, max_configurations: @max_configurations
+        )
+        selections.map do |selection|
+          state = selection.fetch(:state)
+          {
+            state: state,
+            conflict: selection.fetch(:conflict),
+            example: counterexamples.for_conflict(state.id, selection.fetch(:conflict_index))
+          }
+        end
+      end
+
+      # @rbs () -> Array[explain_selection]
+      def selected_conflicts
+        @automaton.states.flat_map do |state|
+          state.conflicts.each_with_index.filter_map do |conflict, conflict_index|
+            next if @state_selector && state.id != @state_selector
+            next if @token_selector && conflict[:symbol] != @token_selector.name
+
+            { state: state, conflict: conflict, conflict_index: conflict_index }
+          end
+        end
+      end
+
+      # @rbs (explain_entry entry) -> Hash[Symbol, untyped]
+      def conflict_document(entry)
+        state = entry.fetch(:state)
+        conflict = entry.fetch(:conflict)
+        example = entry.fetch(:example)
+        document = {
+          state: state.id,
+          type: conflict.fetch(:type).to_s,
+          token: symbol_reference(conflict.fetch(:symbol)),
+          alternatives: conflict_alternatives(conflict),
+          resolution: string_values(conflict.fetch(:resolution)),
+          witness: {
+            kind: example.fetch(:unifying) ? "unifying_counterexample" : "nonunifying_witness",
+            sentence: example.fetch(:sentence).map { |name| symbol_reference(name) },
+            lookahead_index: example.fetch(:lookahead_index),
+            symbol_path: example.fetch(:symbol_path).map { |name| symbol_reference(name) },
+            interpretations: example.fetch(:interpretations).map { |item| interpretation_document(item) }
+          }
+        } #: Hash[Symbol, untyped]
+        document[:midrule_origins] = conflict[:midrule_origins] if conflict[:midrule_origins]
+        document
+      end
+
+      # @rbs (IR::conflict conflict) -> Array[Hash[Symbol, untyped]]
+      def conflict_alternatives(conflict)
+        case conflict[:type]
+        when :shift_reduce
+          [{ kind: "shift", state: conflict.fetch(:shift_to) },
+           { kind: "reduce", production: conflict.fetch(:reduce) }]
+        when :reduce_reduce
+          reduce_reduce = conflict #: IR::reduce_reduce_conflict
+          reduce_reduce[:reductions].map { |production| { kind: "reduce", production: production } }
+        else
+          []
+        end
+      end
+
+      # @rbs (IR::interpretation interpretation) -> Hash[Symbol, untyped]
+      def interpretation_document(interpretation)
+        value = { kind: interpretation.fetch(:kind).to_s,
+                  tree: tree_document(interpretation.fetch(:tree)) } #: Hash[Symbol, untyped]
+        value[:state] = interpretation[:state] if interpretation.key?(:state)
+        value[:production] = interpretation[:production] if interpretation.key?(:production)
+        value
+      end
+
+      # @rbs (untyped tree) -> untyped
+      def tree_document(tree)
+        return symbol_reference(tree.to_s) unless tree.is_a?(Hash)
+
+        value = {} #: Hash[Symbol, untyped]
+        value[:symbol] = symbol_reference(tree[:symbol]) if tree[:symbol]
+        value[:token] = symbol_reference(tree[:token]) if tree[:token]
+        value[:production] = tree[:production] if tree[:production]
+        value[:children] = tree[:children].map { |child| tree_document(child) } if tree[:children]
+        value
+      end
+
+      # @rbs (Hash[Symbol, untyped] value) -> Hash[Symbol, untyped]
+      def string_values(value)
+        value.transform_values { |item| item.is_a?(Symbol) ? item.to_s : item }
+      end
+
+      # @rbs (String name) -> Hash[Symbol, untyped]
+      def symbol_reference(name)
+        symbol = @grammar.symbol(name)
+        return { name: name, display_name: nil, label: name } unless symbol
+
+        token_reference(symbol)
+      end
+
+      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> Hash[Symbol, untyped]
+      def token_reference(symbol, query: nil)
+        value = { name: symbol.name, display_name: symbol.display_name,
+                  label: @labels.fetch(symbol.id, symbol.name) } #: Hash[Symbol, untyped]
+        value[:query] = query if query
+        value
+      end
+
+      # @rbs (Array[String] lines, explain_entry entry, Integer number) -> void
+      def append_conflict(lines, entry, number)
+        state = entry.fetch(:state)
+        conflict = entry.fetch(:conflict)
+        example = entry.fetch(:example)
+        token = @grammar.symbol(conflict.fetch(:symbol))
+        token_text = token ? token_label(token) : conflict.fetch(:symbol)
+        type = conflict.fetch(:type).to_s.tr("_", "/")
+        lines << "Conflict #{number}: state #{state.id}, #{type}, token #{token_text}"
+        append_midrule_origins(lines, conflict)
+        append_witness_steps(lines, state, conflict, example)
+        append_interpretations(lines, example)
+        unless example.fetch(:unifying)
+          lines << "  The search found no shared sentence within the configured budget; this witness is deterministic."
+        end
+        lines << ""
+      end
+
+      # @rbs (Array[String] lines, IR::conflict conflict) -> void
+      def append_midrule_origins(lines, conflict)
+        origins = conflict[:midrule_origins]
+        return unless origins
+
+        origins.each do |origin|
+          lines << "  Midrule action origin: #{origin.fetch(:file)}:#{origin.fetch(:line)}:#{origin.fetch(:column)}"
+        end
+      end
+
+      # @rbs (Array[String] lines, IR::AutomatonState state, IR::conflict conflict,
+      #   IR::counterexample example) -> void
+      def append_witness_steps(lines, state, conflict, example)
+        lines << "  1. Reach state #{state.id} with the witness prefix."
+        sentence = example.fetch(:sentence).map { |name| display_name(name) }
+        sentence.insert(example.fetch(:lookahead_index), "•")
+        kind = example.fetch(:unifying) ? "Unifying counterexample" : "Nonunifying reachability witness"
+        lines << "     #{kind}: #{sentence.join(' ')}"
+        lines << "  2. The lookahead permits these competing actions:"
+        conflict_alternatives(conflict).each { |alternative| lines << "     - #{alternative_text(alternative)}" }
+        resolution = conflict.fetch(:resolution)
+        lines << "  3. Resolution: #{resolution.fetch(:by)} chose #{resolution.fetch(:chose)}."
+      end
+
+      # @rbs (Array[String] lines, IR::counterexample example) -> void
+      def append_interpretations(lines, example)
+        lines << "  Competing derivations:"
+        example.fetch(:interpretations).each_with_index do |interpretation, index|
+          lines << "    #{index + 1}. #{interpretation.fetch(:kind)}"
+          append_tree(lines, interpretation.fetch(:tree), "       ", "")
+        end
+      end
+
+      # @rbs (Hash[Symbol, untyped] alternative) -> String
+      def alternative_text(alternative)
+        return "shift to state #{alternative.fetch(:state)}" if alternative.fetch(:kind) == "shift"
+
+        "reduce by production #{alternative.fetch(:production)}"
+      end
+
+      # @rbs (Array[String] lines, untyped tree, String prefix, String connector) -> void
+      def append_tree(lines, tree, prefix, connector)
+        unless tree.is_a?(Hash)
+          lines << "#{prefix}#{connector}#{display_name(tree.to_s)}"
+          return
+        end
+
+        name = tree[:symbol] || tree[:token]
+        production = tree[:production] ? " (production #{tree[:production]})" : ""
+        lines << "#{prefix}#{connector}#{display_name(name.to_s)}#{production}"
+        children = tree.fetch(:children, [])
+        continuation = { "" => "", "|- " => "|  " }.fetch(connector, "   ")
+        child_prefix = "#{prefix}#{continuation}"
+        children.each_with_index do |child, index|
+          branch = index == children.length - 1 ? "`- " : "|- "
+          append_tree(lines, child, child_prefix, branch)
+        end
+      end
+
+      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> String
+      def token_label(symbol, query: nil)
+        label = if symbol.display_name && symbol.display_name != symbol.name
+                  "#{symbol.name} (display #{symbol.display_name.inspect})"
+                else
+                  symbol.name
+                end
+        query && query != symbol.name ? "#{label}, selected by #{query.inspect}" : label
+      end
+
+      # @rbs (String name) -> String
+      def display_name(name) = @grammar.symbol(name)&.then { |symbol| @labels.fetch(symbol.id, symbol.name) } || name
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end