ibex 0.1.0 → 0.2.0

data/sig/ibex/codegen/action_method_source.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/ibex/codegen/action_method_source.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Builds semantic method source shared by runtime and static shadow output.
+    class ActionMethodSource
+      @generated_action_abi: GeneratedActionABI::Cache
+
+      @grammar: IR::Grammar
+
+      # @rbs (IR::Grammar grammar, ?generated_action_abi: GeneratedActionABI::Cache?) -> void
+      def initialize: (IR::Grammar grammar, ?generated_action_abi: GeneratedActionABI::Cache?) -> void
+
+      # @rbs (IR::Production production, Hash[Symbol, untyped] step, Integer index) -> String
+      def composed_fragment_method_source: (IR::Production production, Hash[Symbol, untyped] step, Integer index) -> String
+
+      # @rbs (IR::Production production, Integer index) -> String
+      def composed_fragment_name: (IR::Production production, Integer index) -> String
+
+      # @rbs (IR::Production production) -> String
+      def compiled_action_method_source: (IR::Production production) -> String
+
+      # @rbs (IR::Production production) -> String
+      def direct_action_method_source: (IR::Production production) -> String
+
+      # @rbs (Integer symbol_id, IR::value_printer printer) -> String
+      def value_printer_method_source: (Integer symbol_id, IR::value_printer printer) -> String
+
+      # @rbs (String source) -> bool
+      def column_sensitive?: (String source) -> bool
+
+      private
+
+      # @rbs (IR::Production production) -> String
+      def action_parameters: (IR::Production production) -> String
+
+      # @rbs (IR::Production production, Integer index) -> String
+      def value_expression: (IR::Production production, Integer index) -> String
+
+      # @rbs (String source, ?production: IR::Production?) -> void
+      def append_parameter_values: (String source, ?production: IR::Production?) -> void
+
+      # @rbs (Array[String] lines, production: IR::Production) -> void
+      def append_direct_parameter_values: (Array[String] lines, production: IR::Production) -> void
+
+      # @rbs (Hash[Symbol, untyped] step) -> String
+      def composed_semantic_code: (Hash[Symbol, untyped] step) -> String
+
+      # @rbs (String source, Array[IR::named_ref] named_refs) -> void
+      def append_named_values: (String source, Array[IR::named_ref] named_refs) -> void
+
+      # @rbs (String source, IR::Production production, IR::Action action) -> void
+      def append_action_body: (String source, IR::Production production, IR::Action action) -> void
+
+      # @rbs (Array[String] lines, IR::Production production, IR::Action? action) -> void
+      def append_direct_action_body: (Array[String] lines, IR::Production production, IR::Action? action) -> void
+
+      # @rbs (IR::Production production, IR::Action action) -> String
+      def semantic_action_code: (IR::Production production, IR::Action action) -> String
+
+      # @rbs (IR::Production production) -> String
+      def default_value_expression: (IR::Production production) -> String
+    end
+  end
+end

data/sig/ibex/codegen/action_source.rbs

@@ -0,0 +1,50 @@
+# Generated from lib/ibex/codegen/action_source.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Generates static-check-only Ruby containing semantic action methods.
+    class ActionSource
+      include RubyAST
+
+      @automaton: IR::Automaton
+
+      @grammar: IR::Grammar
+
+      @omit_action_call: bool
+
+      @method_source: ActionMethodSource
+
+      # @rbs (IR::Automaton automaton, ?omit_action_call: bool?) -> void
+      def initialize: (IR::Automaton automaton, ?omit_action_call: bool?) -> void
+
+      # @rbs () -> String
+      def generate: () -> String
+
+      private
+
+      # @rbs (Array[String] lines) -> void
+      def append_value_printers: (Array[String] lines) -> void
+
+      # @rbs (Array[String] lines) -> void
+      def append_actions: (Array[String] lines) -> void
+
+      # @rbs (Array[String] lines, IR::Production production) -> void
+      def append_composed_actions: (Array[String] lines, IR::Production production) -> void
+
+      # @rbs (Array[String] lines, IR::Production production) -> void
+      def append_action: (Array[String] lines, IR::Production production) -> void
+
+      # @rbs (Array[String] lines, IR::location location, String source) -> void
+      def append_method: (Array[String] lines, IR::location location, String source) -> void
+
+      # @rbs (IR::Production production) -> bool
+      def composed_action?: (IR::Production production) -> bool
+
+      # @rbs () -> [Array[String], String]
+      def class_parts: () -> [ Array[String], String ]
+
+      # @rbs () -> String
+      def grammar_digest_comment: () -> String
+    end
+  end
+end

data/sig/ibex/codegen/ambiguity.rbs

@@ -0,0 +1,60 @@
+# Generated from lib/ibex/codegen/ambiguity.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    type ambiguity_search = { max_tokens: Integer, max_configurations: Integer }
+
+    type ambiguity_summary = { conflicts: Integer, ambiguous: Integer, not_found: Integer, configuration_budget_exhausted: Integer }
+
+    type ambiguity_check = { state: Integer, type: String, token: String, result: String, sentence: Array[String], lookahead_index: Integer?, interpretations: Array[IR::interpretation], explored_configurations: Integer, configuration_budget_exhausted: bool }
+
+    type ambiguity_document = { ibex_check: String, schema_version: Integer, algorithm: String, search: ambiguity_search, status: String, summary: ambiguity_summary, conflicts: Array[ambiguity_check] }
+
+    # Renders a bounded ambiguity search over every parser conflict.
+    class Ambiguity
+      SCHEMA_VERSION: Integer
+
+      @checks: Array[ambiguity_check]
+
+      @max_configurations: Integer
+
+      @max_tokens: Integer
+
+      @grammar: IR::Grammar
+
+      @automaton: IR::Automaton
+
+      # @rbs (IR::Automaton automaton, ?max_tokens: Integer, ?max_configurations: Integer) -> void
+      def initialize: (IR::Automaton automaton, ?max_tokens: Integer, ?max_configurations: Integer) -> void
+
+      # @rbs () -> Integer
+      def exit_status: () -> Integer
+
+      # @rbs () -> ambiguity_document
+      def to_h: () -> ambiguity_document
+
+      # @rbs () -> String
+      def render_text: () -> String
+
+      private
+
+      # @rbs () -> String
+      def status: () -> String
+
+      # @rbs () -> ambiguity_summary
+      def summary: () -> ambiguity_summary
+
+      # @rbs () -> Array[ambiguity_check]
+      def check_conflicts: () -> Array[ambiguity_check]
+
+      # @rbs (IR::AutomatonState state, IR::conflict conflict) -> ambiguity_check
+      def check_conflict: (IR::AutomatonState state, IR::conflict conflict) -> ambiguity_check
+
+      # @rbs (Array[Integer] ids) -> Array[String]
+      def symbol_names: (Array[Integer] ids) -> Array[String]
+
+      # @rbs (Array[String] lines, ambiguity_check check, Integer number) -> void
+      def append_check: (Array[String] lines, ambiguity_check check, Integer number) -> void
+    end
+  end
+end

data/sig/ibex/codegen/cst_metadata.rbs

@@ -0,0 +1,59 @@
+# Generated from lib/ibex/codegen/cst_metadata.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Builds the deterministic kind space embedded in CST-aware parser tables.
+    class CSTMetadata
+      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: Array[String]
+
+      SYNTHETIC_KINDS: Array[String]
+
+      @grammar: IR::Grammar
+
+      @trivia_policy: Symbol
+
+      # @rbs (IR::Grammar grammar, ?trivia_policy: Symbol | String) -> void
+      def initialize: (IR::Grammar grammar, ?trivia_policy: Symbol | String) -> void
+
+      # Return table-ready CST metadata with stable insertion order.
+      # @rbs () -> metadata
+      def build: () -> metadata
+
+      private
+
+      # @rbs (Symbol | String policy) -> Symbol
+      def normalize_trivia_policy: (Symbol | String policy) -> Symbol
+
+      # @rbs (Array[String] names) -> Hash[String, Integer]
+      def append_named_kinds: (Array[String] names) -> Hash[String, Integer]
+
+      # @rbs (Array[String] names, Array[String] additions) -> Hash[String, Integer]
+      def append_kinds: (Array[String] names, Array[String] additions) -> Hash[String, Integer]
+
+      # @rbs (Array[Integer] ids) -> Array[Integer]
+      def half_open_range: (Array[Integer] ids) -> Array[Integer]
+
+      # @rbs (Hash[String, Integer] named) -> Hash[Integer, Integer]
+      def named_nonterminals: (Hash[String, Integer] named) -> Hash[Integer, Integer]
+
+      # @rbs (Hash[String, Integer] named) -> Hash[Integer, slot]
+      def slot_metadata: (Hash[String, Integer] named) -> Hash[Integer, slot]
+
+      # @rbs (Integer index, Integer symbol_id) -> field_slot
+      def field_slot: (Integer index, Integer symbol_id) -> field_slot
+
+      # @rbs (Integer symbol_id) -> Symbol?
+      def repetition_extraction: (Integer symbol_id) -> Symbol?
+    end
+  end
+end

data/sig/ibex/codegen/documentation.rbs

@@ -0,0 +1,50 @@
+# Generated from lib/ibex/codegen/documentation.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Renders normalized user rules as deterministic Markdown, HTML, or railroad SVG.
+    module Documentation
+      FORMATS: Array[String]
+
+      # @rbs (IR::Grammar grammar, format: String | Symbol) -> String
+      def self.render: (IR::Grammar grammar, format: String | Symbol) -> String
+
+      # @rbs (IR::Grammar grammar) -> String
+      private def self.render_markdown: (IR::Grammar grammar) -> String
+
+      # @rbs (Array[String] lines, String? documentation) -> void
+      private def self.append_markdown_documentation: (Array[String] lines, String? documentation) -> void
+
+      # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels) -> String
+      private def self.markdown_alternative: (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels) -> String
+
+      # @rbs (IR::Grammar grammar) -> String
+      private def self.render_html: (IR::Grammar grammar) -> String
+
+      # @rbs (String title) -> Array[String]
+      private def self.html_start: (String title) -> Array[String]
+
+      # @rbs (Array[String] lines, IR::Grammar grammar, IR::GrammarSymbol symbol,
+      #   Array[IR::Production] productions, Hash[Integer, String] labels) -> void
+      private def self.append_html_rule: (Array[String] lines, IR::Grammar grammar, IR::GrammarSymbol symbol, Array[IR::Production] productions, Hash[Integer, String] labels) -> void
+
+      # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels) -> String
+      private def self.html_alternative: (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels) -> String
+
+      # @rbs (IR::Grammar grammar) -> Array[[IR::GrammarSymbol, Array[IR::Production]]]
+      private def self.rule_groups: (IR::Grammar grammar) -> Array[[ IR::GrammarSymbol, Array[IR::Production] ]]
+
+      # @rbs (String value) -> String
+      private def self.markdown_code: (String value) -> String
+
+      # @rbs (String value) -> bool
+      private def self.markdown_code_padding?: (String value) -> bool
+
+      # @rbs (String value) -> String
+      private def self.markdown_escape: (String value) -> String
+
+      # @rbs (String value) -> String
+      private def self.html_escape: (String value) -> String
+    end
+  end
+end

data/sig/ibex/codegen/explain.rbs

@@ -0,0 +1,85 @@
+# Generated from lib/ibex/codegen/explain.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    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: Integer
+
+      # @rbs (IR::Automaton automaton, ?state: Integer?, ?token: String?, ?max_tokens: Integer,
+      #   ?max_configurations: Integer) -> void
+      def initialize: (IR::Automaton automaton, ?state: Integer?, ?token: String?, ?max_tokens: Integer, ?max_configurations: Integer) -> void
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def to_h: () -> Hash[Symbol, untyped]
+
+      # @rbs () -> String
+      def render_text: () -> String
+
+      private
+
+      # @rbs (String? query) -> IR::GrammarSymbol?
+      def resolve_token: (String? query) -> IR::GrammarSymbol?
+
+      # @rbs () -> void
+      def validate_state!: () -> void
+
+      # @rbs () -> Array[explain_entry]
+      def select_entries: () -> Array[explain_entry]
+
+      # @rbs () -> Array[explain_selection]
+      def selected_conflicts: () -> Array[explain_selection]
+
+      # @rbs (explain_entry entry) -> Hash[Symbol, untyped]
+      def conflict_document: (explain_entry entry) -> Hash[Symbol, untyped]
+
+      # @rbs (IR::conflict conflict) -> Array[Hash[Symbol, untyped]]
+      def conflict_alternatives: (IR::conflict conflict) -> Array[Hash[Symbol, untyped]]
+
+      # @rbs (IR::interpretation interpretation) -> Hash[Symbol, untyped]
+      def interpretation_document: (IR::interpretation interpretation) -> Hash[Symbol, untyped]
+
+      # @rbs (untyped tree) -> untyped
+      def tree_document: (untyped tree) -> untyped
+
+      # @rbs (Hash[Symbol, untyped] value) -> Hash[Symbol, untyped]
+      def string_values: (Hash[Symbol, untyped] value) -> Hash[Symbol, untyped]
+
+      # @rbs (String name) -> Hash[Symbol, untyped]
+      def symbol_reference: (String name) -> Hash[Symbol, untyped]
+
+      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> Hash[Symbol, untyped]
+      def token_reference: (IR::GrammarSymbol symbol, ?query: String?) -> Hash[Symbol, untyped]
+
+      # @rbs (Array[String] lines, explain_entry entry, Integer number) -> void
+      def append_conflict: (Array[String] lines, explain_entry entry, Integer number) -> void
+
+      # @rbs (Array[String] lines, IR::conflict conflict) -> void
+      def append_midrule_origins: (Array[String] lines, IR::conflict conflict) -> void
+
+      # @rbs (Array[String] lines, IR::AutomatonState state, IR::conflict conflict,
+      #   IR::counterexample example) -> void
+      def append_witness_steps: (Array[String] lines, IR::AutomatonState state, IR::conflict conflict, IR::counterexample example) -> void
+
+      # @rbs (Array[String] lines, IR::counterexample example) -> void
+      def append_interpretations: (Array[String] lines, IR::counterexample example) -> void
+
+      # @rbs (Hash[Symbol, untyped] alternative) -> String
+      def alternative_text: (Hash[Symbol, untyped] alternative) -> String
+
+      # @rbs (Array[String] lines, untyped tree, String prefix, String connector) -> void
+      def append_tree: (Array[String] lines, untyped tree, String prefix, String connector) -> void
+
+      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> String
+      def token_label: (IR::GrammarSymbol symbol, ?query: String?) -> String
+
+      # @rbs (String name) -> String
+      def display_name: (String name) -> String
+    end
+  end
+end

data/sig/ibex/codegen/generated_action_abi.rbs

@@ -0,0 +1,101 @@
+# Generated from lib/ibex/codegen/generated_action_abi.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Selects the smallest generated semantic-action ABI that preserves the
+    # action's declared inputs.
+    # rubocop:disable Metrics/ModuleLength -- ABI proof and source rewriting must evolve together.
+    module GeneratedActionABI
+      LEGACY_PARAMETERS: Array[String]
+
+      SIMPLE_POSITIONAL_READ: Regexp
+
+      SIMPLE_POSITIONAL_UNSAFE: Regexp
+
+      # Keeps semantic-action analysis local to one code-generation run.
+      class Cache
+        @values_only: Hash[Integer, bool]
+
+        @borrowed_values: Hash[Integer, bool]
+
+        @positional_actions: Hash[Integer, String?]
+
+        # @rbs () -> void
+        def initialize: () -> void
+
+        # @rbs (IR::Production production) -> bool
+        def values_only?: (IR::Production production) -> bool
+
+        # @rbs (IR::Production production) -> bool
+        def borrowed_values?: (IR::Production production) -> bool
+
+        # @rbs (IR::Production production) -> String?
+        def positional_action_source: (IR::Production production) -> String?
+
+        # @rbs (IR::Production production) -> bool
+        def positional_values?: (IR::Production production) -> bool
+      end
+
+      # @rbs (IR::Production production) -> bool
+      def self?.values_only?: (IR::Production production) -> bool
+
+      # The direct runtime can share one reduction-values array with an action
+      # and a hook installed by that action only when the action cannot mutate
+      # or retain the array itself. Element reads and parallel assignment copy
+      # values out without exposing the container.
+      # @rbs (IR::Production production, ?analysis: singleton(GeneratedActionABI) | Cache) -> bool
+      def self?.borrowed_values?: (IR::Production production, ?analysis: singleton(GeneratedActionABI) | Cache) -> bool
+
+      # Return semantic source rewritten for zero-to-four positional RHS
+      # arguments, or nil when the values container remains observable.
+      # @rbs (IR::Production production, ?analysis: singleton(GeneratedActionABI) | Cache) -> String?
+      def self?.positional_action_source: (IR::Production production, ?analysis: singleton(GeneratedActionABI) | Cache) -> String?
+
+      # @rbs (String source, Array[String] parameters) -> String?
+      def self?.fast_positional_action_source: (String source, Array[String] parameters) -> String?
+
+      # @rbs (IR::Production production) -> bool
+      def self?.positional_values?: (IR::Production production) -> bool
+
+      # Avoid loading a Ruby parser for the overwhelmingly common generated
+      # action shape. This accepts only a single result assignment (or a bare
+      # expression), simple numeric val reads, and no further assignment.
+      # Anything less obvious falls back to Ripper below.
+      # @rbs (String source) -> bool
+      def self?.simple_indexed_values_action?: (String source) -> bool
+
+      # Keep the most common identity action off the Ripper load path. The
+      # whole-source match excludes strings, comments, receivers, and compound
+      # expressions before replacing the one direct read.
+      # @rbs (String source, Array[String] parameters) -> String?
+      def self?.simple_positional_action_source: (String source, Array[String] parameters) -> String?
+
+      # Rewrite the common string/comment/regexp-free action shape without
+      # loading Ripper. The borrowed-values proof has already rejected writes
+      # and escaping uses of the values container.
+      # @rbs (String source, Array[String] parameters) -> String?
+      def self?.simple_indexed_positional_action_source: (String source, Array[String] parameters) -> String?
+
+      # @rbs (Array[untyped] tokens, Array[String] parameters) -> String?
+      def self?.rewrite_positional_values: (Array[untyped] tokens, Array[String] parameters) -> String?
+
+      # @rbs (Array[untyped] tokens, Integer index, Array[String] parameters) -> [String, Integer]?
+      def self?.positional_value_reference: (Array[untyped] tokens, Integer index, Array[String] parameters) -> [ String, Integer ]?
+
+      # @rbs (Array[untyped] tokens, Integer index) -> bool
+      def self?.receiver_before_value?: (Array[untyped] tokens, Integer index) -> bool
+
+      # @rbs (String source) -> bool
+      def self?.references_legacy_parameter?: (String source) -> bool
+
+      # @rbs (untyped node, ?untyped parent, ?Integer? child_index) -> bool
+      def self?.read_only_value_references?: (untyped node, ?untyped parent, ?Integer? child_index) -> bool
+
+      # @rbs (untyped node) -> bool
+      def self?.value_reference?: (untyped node) -> bool
+
+      # @rbs (untyped parent, Integer? child_index) -> bool
+      def self?.safe_value_reference?: (untyped parent, Integer? child_index) -> bool
+    end
+  end
+end

data/sig/ibex/codegen/html.rbs

@@ -8,6 +8,22 @@ module Ibex
 
       private def self.state_sections: (IR::Automaton automaton, IR::Grammar grammar, Hash[Integer, String] labels) -> String
 
+      private def controls: (IR::Automaton automaton) -> String
+
+      private def self.controls: (IR::Automaton automaton) -> String
+
+      private def styles: () -> String
+
+      private def self.styles: () -> String
+
+      private def interaction_script: () -> String
+
+      private def self.interaction_script: () -> String
+
+      private def one_hop_neighbors: (IR::Automaton automaton, Integer state_id) -> Array[Integer]
+
+      private def self.one_hop_neighbors: (IR::Automaton automaton, Integer state_id) -> Array[Integer]
+
       private def item_html: (IR::AutomatonItem item, IR::Grammar grammar, Hash[Integer, String] labels) -> String
 
       private def self.item_html: (IR::AutomatonItem item, IR::Grammar grammar, Hash[Integer, String] labels) -> String
@@ -16,9 +32,9 @@ module Ibex
 
       private def self.rule_sections: (IR::Grammar grammar, Hash[Integer, String] labels) -> String
 
-      private def conflict_sections: (IR::Automaton automaton) -> String
+      private def conflict_sections: (IR::Automaton automaton, IR::Grammar grammar, Hash[Integer, String] labels) -> String
 
-      private def self.conflict_sections: (IR::Automaton automaton) -> String
+      private def self.conflict_sections: (IR::Automaton automaton, IR::Grammar grammar, Hash[Integer, String] labels) -> String
 
       private def escape: (String value) -> String
 

data/sig/ibex/codegen/mermaid.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/ibex/codegen/mermaid.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Renders an Automaton IR graph as a GitHub-compatible Mermaid flowchart.
+    module Mermaid
+      # @rbs (IR::Automaton automaton) -> String
+      def self?.render: (IR::Automaton automaton) -> String
+
+      private
+
+      # @rbs (String value) -> String
+      def self?.escape: (String value) -> String
+    end
+  end
+end

data/sig/ibex/codegen/railroad.rbs

@@ -0,0 +1,82 @@
+# Generated from lib/ibex/codegen/railroad.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Renders normalized Grammar IR as a self-contained SVG railroad diagram.
+    module Railroad
+      CHAR_WIDTH: Integer
+
+      BOX_HEIGHT: Integer
+
+      BOX_PADDING: Integer
+
+      TRACK_GAP: Integer
+
+      ROW_HEIGHT: Integer
+
+      SECTION_HEADER: Integer
+
+      SECTION_GAP: Integer
+
+      PAGE_PADDING: Integer
+
+      TITLE_HEIGHT: Integer
+
+      EPSILON_WIDTH: Integer
+
+      START_RADIUS: Integer
+
+      END_RADIUS: Integer
+
+      MIN_RAIL_X: Integer
+
+      # @rbs STYLE: String
+      STYLE: ::String
+
+      extend RailroadDocumentation
+
+      # @rbs (IR::Grammar grammar) -> String
+      def self.render: (IR::Grammar grammar) -> String
+
+      # @rbs (IR::Grammar grammar) -> Array[[IR::GrammarSymbol, Array[IR::Production]]]
+      private def self.production_groups: (IR::Grammar grammar) -> Array[[ IR::GrammarSymbol, Array[IR::Production] ]]
+
+      # @rbs (IR::Grammar grammar, Array[[IR::GrammarSymbol, Array[IR::Production]]] groups,
+      #   Hash[Integer, String] labels, Integer rail_x) -> Integer
+      private def self.document_width: (IR::Grammar grammar, Array[[ IR::GrammarSymbol, Array[IR::Production] ]] groups, Hash[Integer, String] labels, Integer rail_x) -> Integer
+
+      # @rbs (Array[[IR::GrammarSymbol, Array[IR::Production]]] groups) -> Integer
+      private def self.document_height: (Array[[ IR::GrammarSymbol, Array[IR::Production] ]] groups) -> Integer
+
+      # @rbs (IR::Grammar grammar, Integer width, Integer height) -> Array[String]
+      private def self.document_start: (IR::Grammar grammar, Integer width, Integer height) -> Array[String]
+
+      # @rbs (Array[String] lines, IR::Grammar grammar,
+      #   Array[[IR::GrammarSymbol, Array[IR::Production]]] groups,
+      #   Hash[Integer, String] labels, Integer rail_x) -> void
+      private def self.append_sections: (Array[String] lines, IR::Grammar grammar, Array[[ IR::GrammarSymbol, Array[IR::Production] ]] groups, Hash[Integer, String] labels, Integer rail_x) -> void
+
+      # @rbs (Array[String] lines, IR::Grammar grammar, Array[IR::Production] productions,
+      #   Hash[Integer, String] labels, Integer rail_x, Integer header_height) -> void
+      private def self.append_productions: (Array[String] lines, IR::Grammar grammar, Array[IR::Production] productions, Hash[Integer, String] labels, Integer rail_x, Integer header_height) -> void
+
+      # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels,
+      #   Integer rail_x, Integer offset_y) -> Array[String]
+      private def self.production_lines: (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels, Integer rail_x, Integer offset_y) -> Array[String]
+
+      # @rbs (Array[String] lines, IR::Grammar grammar, IR::Production production,
+      #   Hash[Integer, String] labels, Integer cursor) -> Integer
+      private def self.append_rhs: (Array[String] lines, IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels, Integer cursor) -> Integer
+
+      # @rbs (Array[String] lines, Integer cursor) -> Integer
+      private def self.append_epsilon: (Array[String] lines, Integer cursor) -> Integer
+
+      # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels,
+      #   Integer rail_x) -> Integer
+      private def self.row_end_x: (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels, Integer rail_x) -> Integer
+
+      # @rbs (String value) -> Integer
+      private def self.label_width: (String value) -> Integer
+    end
+  end
+end

data/sig/ibex/codegen/railroad_documentation.rbs

@@ -0,0 +1,31 @@
+# Generated from lib/ibex/codegen/railroad_documentation.rb with RBS::Inline
+
+module Ibex
+  module Codegen
+    # Documentation layout helpers mixed into the railroad renderer singleton.
+    module RailroadDocumentation
+      DOCUMENTATION_COLUMNS: Integer
+
+      DOCUMENTATION_LINE_HEIGHT: Integer
+
+      DOCUMENTATION_GAP: Integer
+
+      private
+
+      # @rbs (Array[String] lines, IR::GrammarSymbol symbol) -> void
+      def append_rule_documentation: (Array[String] lines, IR::GrammarSymbol symbol) -> void
+
+      # @rbs (IR::GrammarSymbol symbol) -> Integer
+      def section_header_height: (IR::GrammarSymbol symbol) -> Integer
+
+      # @rbs (String? documentation) -> Array[String]
+      def documentation_lines: (String? documentation) -> Array[String]
+
+      # @rbs (String | Integer value) -> String
+      def escape: (String | Integer value) -> String
+
+      # @rbs (Integer from, Integer to) -> String
+      def track: (Integer from, Integer to) -> String
+    end
+  end
+end