ibex 0.1.0 → 0.2.0

data/lib/ibex/codegen/railroad.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "symbol_labels"
+require_relative "railroad_documentation"
+
+module Ibex
+  module Codegen
+    # Renders normalized Grammar IR as a self-contained SVG railroad diagram.
+    module Railroad
+      CHAR_WIDTH = 8 #: Integer
+      BOX_HEIGHT = 28 #: Integer
+      BOX_PADDING = 20 #: Integer
+      TRACK_GAP = 18 #: Integer
+      ROW_HEIGHT = 46 #: Integer
+      SECTION_HEADER = 30 #: Integer
+      SECTION_GAP = 18 #: Integer
+      PAGE_PADDING = 20 #: Integer
+      TITLE_HEIGHT = 48 #: Integer
+      EPSILON_WIDTH = 34 #: Integer
+      START_RADIUS = 4 #: Integer
+      END_RADIUS = 6 #: Integer
+      MIN_RAIL_X = 180 #: Integer
+      # @rbs STYLE: String
+      STYLE = <<~CSS
+        text { fill: #172033; font: 14px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+        .diagram-title { font-size: 18px; font-weight: 700; }
+        .rule-name { font-weight: 700; }
+        .rule-documentation { fill: #4b5565; font: 12px system-ui, sans-serif; }
+        .production-id { fill: #697386; font-size: 11px; text-anchor: end; }
+        .track { fill: none; stroke: #697386; stroke-width: 2; }
+        .start { fill: #172033; }
+        .end { fill: #fff; stroke: #172033; stroke-width: 2; }
+        .end-dot { fill: #172033; }
+        .symbol { stroke: #172033; stroke-width: 1.5; }
+        .terminal { fill: #fff3df; }
+        .nonterminal { fill: #e8f1ff; }
+        .symbol-label { text-anchor: middle; }
+        .epsilon { fill: #697386; font-style: italic; text-anchor: middle; }
+      CSS
+
+      extend RailroadDocumentation
+
+      class << self
+        # @rbs (IR::Grammar grammar) -> String
+        def render(grammar)
+          labels = SymbolLabels.build(grammar)
+          groups = production_groups(grammar)
+          rail_x = [MIN_RAIL_X, groups.map { |symbol, _| label_width(labels.fetch(symbol.id)) }.max.to_i + 44].max
+          width = document_width(grammar, groups, labels, rail_x)
+          height = document_height(groups)
+          lines = document_start(grammar, width, height)
+          append_sections(lines, grammar, groups, labels, rail_x)
+          lines << "</svg>"
+          "#{lines.join("\n")}\n"
+        end
+
+        private
+
+        # @rbs (IR::Grammar grammar) -> Array[[IR::GrammarSymbol, Array[IR::Production]]]
+        def production_groups(grammar)
+          grouped = grammar.productions.group_by(&:lhs)
+          grammar.nonterminals.map { |symbol| [symbol, grouped.fetch(symbol.id, [])] }
+        end
+
+        # @rbs (IR::Grammar grammar, Array[[IR::GrammarSymbol, Array[IR::Production]]] groups,
+        #   Hash[Integer, String] labels, Integer rail_x) -> Integer
+        def document_width(grammar, groups, labels, rail_x)
+          rows = groups.flat_map(&:last)
+          widest = rows.map { |production| row_end_x(grammar, production, labels, rail_x) }.max
+          documentation_width = groups.flat_map { |symbol, _| documentation_lines(symbol.documentation) }
+                                      .map { |line| label_width(line) + (PAGE_PADDING * 2) }.max
+          [widest.to_i + PAGE_PADDING, documentation_width.to_i,
+           label_width("#{grammar.class_name} grammar") + (PAGE_PADDING * 2), 360].max
+        end
+
+        # @rbs (Array[[IR::GrammarSymbol, Array[IR::Production]]] groups) -> Integer
+        def document_height(groups)
+          sections = groups.sum do |symbol, productions|
+            section_header_height(symbol) + ([productions.length, 1].max * ROW_HEIGHT)
+          end
+          TITLE_HEIGHT + sections + (SECTION_GAP * [groups.length - 1, 0].max) + PAGE_PADDING
+        end
+
+        # @rbs (IR::Grammar grammar, Integer width, Integer height) -> Array[String]
+        def document_start(grammar, width, height)
+          title = escape(grammar.class_name)
+          [
+            %(<?xml version="1.0" encoding="UTF-8"?>),
+            %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{width} #{height}" width="#{width}" ),
+            %(     height="#{height}" role="img" aria-labelledby="railroad-title">),
+            "  <title id=\"railroad-title\">Railroad diagram for #{title}</title>",
+            "  <style>",
+            STYLE.lines.map { |line| "    #{line.rstrip}" }.join("\n"),
+            "  </style>",
+            "  <text class=\"diagram-title\" x=\"#{PAGE_PADDING}\" y=\"30\">#{title} grammar</text>"
+          ]
+        end
+
+        # @rbs (Array[String] lines, IR::Grammar grammar,
+        #   Array[[IR::GrammarSymbol, Array[IR::Production]]] groups,
+        #   Hash[Integer, String] labels, Integer rail_x) -> void
+        def append_sections(lines, grammar, groups, labels, rail_x)
+          y = TITLE_HEIGHT
+          groups.each do |symbol, productions|
+            lines << %(  <g id="nonterminal-#{escape(symbol.id)}" class="rule" transform="translate(0 #{y})">)
+            lines << %(    <text class="rule-name" x="#{PAGE_PADDING}" y="20">#{escape(labels.fetch(symbol.id))}</text>)
+            append_rule_documentation(lines, symbol)
+            header_height = section_header_height(symbol)
+            append_productions(lines, grammar, productions, labels, rail_x, header_height)
+            lines << "  </g>"
+            y += header_height + ([productions.length, 1].max * ROW_HEIGHT) + SECTION_GAP
+          end
+        end
+
+        # @rbs (Array[String] lines, IR::Grammar grammar, Array[IR::Production] productions,
+        #   Hash[Integer, String] labels, Integer rail_x, Integer header_height) -> void
+        def append_productions(lines, grammar, productions, labels, rail_x, header_height)
+          if productions.empty?
+            lines << %(    <text class="epsilon" x="#{rail_x}" y="#{header_height + 18}">∅</text>)
+            return
+          end
+          productions.each_with_index do |production, index|
+            y = header_height + (index * ROW_HEIGHT) + (BOX_HEIGHT / 2)
+            lines.concat(production_lines(grammar, production, labels, rail_x, y))
+          end
+        end
+
+        # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels,
+        #   Integer rail_x, Integer offset_y) -> Array[String]
+        def production_lines(grammar, production, labels, rail_x, offset_y)
+          lines = [
+            %(<g class="production" data-production="#{escape(production.id)}" transform="translate(0 #{offset_y})">)
+          ]
+          lines << %(<text class="production-id" x="#{rail_x - 14}" y="4">p#{escape(production.id)}</text>)
+          lines << %(<circle class="start" cx="#{rail_x}" cy="0" r="#{START_RADIUS}"/>)
+          cursor = rail_x + START_RADIUS
+          lines << track(cursor, cursor + TRACK_GAP)
+          cursor += TRACK_GAP
+          cursor = append_rhs(lines, grammar, production, labels, cursor)
+          end_x = cursor + TRACK_GAP + END_RADIUS
+          lines << track(cursor, end_x - END_RADIUS)
+          lines << %(<circle class="end" cx="#{end_x}" cy="0" r="#{END_RADIUS}"/>)
+          lines << %(<circle class="end-dot" cx="#{end_x}" cy="0" r="2"/>)
+          lines << "</g>"
+          lines.map { |line| "    #{line}" }
+        end
+
+        # @rbs (Array[String] lines, IR::Grammar grammar, IR::Production production,
+        #   Hash[Integer, String] labels, Integer cursor) -> Integer
+        def append_rhs(lines, grammar, production, labels, cursor)
+          return append_epsilon(lines, cursor) if production.rhs.empty?
+
+          production.rhs.each_with_index do |symbol_id, index|
+            symbol = grammar.symbol_by_id(symbol_id) || raise(Ibex::Error, "missing grammar symbol id #{symbol_id}")
+            width = label_width(labels.fetch(symbol_id))
+            kind = symbol.terminal? ? "terminal" : "nonterminal"
+            lines << "<rect class=\"symbol #{kind}\" x=\"#{cursor}\" y=\"#{-(BOX_HEIGHT / 2)}\" " \
+                     "width=\"#{width}\" height=\"#{BOX_HEIGHT}\" rx=\"5\"/>"
+            lines << "<text class=\"symbol-label\" x=\"#{cursor + (width / 2)}\" y=\"5\">" \
+                     "#{escape(labels.fetch(symbol_id))}</text>"
+            cursor += width
+            next if index == production.rhs.length - 1
+
+            lines << track(cursor, cursor + TRACK_GAP)
+            cursor += TRACK_GAP
+          end
+          cursor
+        end
+
+        # @rbs (Array[String] lines, Integer cursor) -> Integer
+        def append_epsilon(lines, cursor)
+          lines << track(cursor, cursor + EPSILON_WIDTH)
+          lines << %(<text class="epsilon" x="#{cursor + (EPSILON_WIDTH / 2)}" y="-6">ε</text>)
+          cursor + EPSILON_WIDTH
+        end
+
+        # @rbs (IR::Grammar grammar, IR::Production production, Hash[Integer, String] labels,
+        #   Integer rail_x) -> Integer
+        def row_end_x(grammar, production, labels, rail_x)
+          widths = production.rhs.map do |symbol_id|
+            raise Ibex::Error, "missing grammar symbol id #{symbol_id}" unless grammar.symbol_by_id(symbol_id)
+
+            label_width(labels.fetch(symbol_id))
+          end
+          content = widths.empty? ? EPSILON_WIDTH : widths.sum + (TRACK_GAP * [widths.length - 1, 0].max)
+          rail_x + START_RADIUS + TRACK_GAP + content + TRACK_GAP + (END_RADIUS * 2)
+        end
+
+        # @rbs (String value) -> Integer
+        def label_width(value)
+          glyph_width = value.each_char.sum { |character| character.ascii_only? ? CHAR_WIDTH : CHAR_WIDTH * 2 }
+          [glyph_width + BOX_PADDING, 38].max
+        end
+      end
+    end
+  end
+end

data/lib/ibex/codegen/railroad_documentation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Ibex
+  module Codegen
+    # Documentation layout helpers mixed into the railroad renderer singleton.
+    module RailroadDocumentation
+      DOCUMENTATION_COLUMNS = 72 #: Integer
+      DOCUMENTATION_LINE_HEIGHT = 18 #: Integer
+      DOCUMENTATION_GAP = 8 #: Integer
+
+      private
+
+      # @rbs (Array[String] lines, IR::GrammarSymbol symbol) -> void
+      def append_rule_documentation(lines, symbol)
+        # @type self: singleton(Railroad)
+        documentation = symbol.documentation
+        return unless documentation
+
+        lines << "    <desc>#{escape(documentation)}</desc>"
+        documentation_lines(documentation).each_with_index do |line, index|
+          y = Railroad::SECTION_HEADER + DOCUMENTATION_GAP + (index * DOCUMENTATION_LINE_HEIGHT)
+          lines << %(    <text class="rule-documentation" x="#{Railroad::PAGE_PADDING}" y="#{y}">#{escape(line)}</text>)
+        end
+      end
+
+      # @rbs (IR::GrammarSymbol symbol) -> Integer
+      def section_header_height(symbol)
+        # @type self: singleton(Railroad)
+        lines = documentation_lines(symbol.documentation)
+        return Railroad::SECTION_HEADER if lines.empty?
+
+        Railroad::SECTION_HEADER + DOCUMENTATION_GAP + (lines.length * DOCUMENTATION_LINE_HEIGHT)
+      end
+
+      # @rbs (String? documentation) -> Array[String]
+      def documentation_lines(documentation)
+        return [] unless documentation
+
+        documentation.split("\n", -1).flat_map do |line|
+          characters = line.each_char.to_a
+          characters.empty? ? [""] : characters.each_slice(DOCUMENTATION_COLUMNS).map(&:join)
+        end
+      end
+
+      # @rbs (String | Integer value) -> String
+      def escape(value)
+        xml = value.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+                   .gsub(/[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/u, "\uFFFD")
+        xml.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+           .gsub('"', "&quot;").gsub("'", "&apos;")
+      end
+
+      # @rbs (Integer from, Integer to) -> String
+      def track(from, to)
+        %(<line class="track" x1="#{from}" y1="0" x2="#{to}" y2="0"/>)
+      end
+    end
+  end
+end

data/lib/ibex/codegen/rbs.rb

@@ -1,18 +1,26 @@
 # frozen_string_literal: true
 
+require_relative "generated_action_abi"
+require_relative "cst_metadata"
+
 module Ibex
   module Codegen
     # Generates an RBS declaration for the public surface of a generated parser.
+    # rubocop:disable Metrics/ClassLength -- one generator owns the complete parser signature.
     class RBS
       # @rbs @automaton: IR::Automaton
       # @rbs @grammar: IR::Grammar
       # @rbs @superclass: String
+      # @rbs @omit_action_call: bool
+      # @rbs @generated_action_abi: GeneratedActionABI::Cache
 
-      # @rbs (IR::Automaton automaton, ?superclass: String?) -> void
-      def initialize(automaton, superclass: nil)
+      # @rbs (IR::Automaton automaton, ?superclass: String?, ?omit_action_call: bool?) -> void
+      def initialize(automaton, superclass: nil, omit_action_call: nil)
         @automaton = automaton
         @grammar = automaton.grammar
         @superclass = superclass || @grammar.superclass || "Ibex::Runtime::Parser"
+        @omit_action_call = omit_action_call.nil? ? @grammar.options[:omit_action_call] : omit_action_call
+        @generated_action_abi = GeneratedActionABI::Cache.new
       end
 
       # @rbs () -> String
@@ -21,7 +29,12 @@ module Ibex
         modules, class_name = class_parts
         modules.each { |name| lines << "module #{name}" }
         lines << "class #{class_name} < #{@superclass}"
+        append_ast_contract(lines)
+        append_syntax_contract(lines)
         append_contract(lines)
+        append_lexer_contract(lines)
+        append_value_printer_signatures(lines)
+        append_actions(lines)
         lines << "end"
         modules.reverse_each { lines << "end" }
         "#{lines.join("\n")}\n"
@@ -29,14 +42,321 @@ module Ibex
 
       private
 
+      # @rbs (Array[String] lines) -> void
+      def append_ast_contract(lines)
+        definitions = ast_node_definitions
+        return if definitions.empty?
+
+        lines << "  module AST"
+        definitions.each_value { |node| append_ast_node_contract(lines, node) }
+        append_visitor_contract(lines, definitions)
+        append_listener_contract(lines, definitions)
+        lines.push("  end", "")
+      end
+
+      # @rbs (Array[String] lines) -> void
+      def append_syntax_contract(lines)
+        definitions = syntax_node_definitions
+        return if definitions.empty? || @grammar.options[:cst] != true
+
+        lines << "  module Syntax"
+        definitions.each_value { |definition| append_syntax_node_contract(lines, definition) }
+        lines.push("  end", "")
+      end
+
+      # @rbs () -> Hash[String, Hash[Symbol, untyped]]
+      def syntax_node_definitions
+        metadata = CSTMetadata.new(@grammar).build
+        slots = metadata.fetch(:slots)
+        definitions = {} #: Hash[String, Hash[Symbol, untyped]]
+        @grammar.productions.each do |production|
+          node = production.node
+          next unless node
+
+          slot = slots.fetch(production.id)
+          name = node.fetch(:name)
+          previous = definitions[name]
+          fields = previous ? merge_syntax_fields(previous.fetch(:fields), slot.fetch(:fields)) : slot.fetch(:fields)
+          definitions[name] = { name: name, kind: slot.fetch(:node_kind), fields: fields }.freeze
+        end
+        definitions
+      end
+
+      # @rbs (Hash[String, untyped] left, Hash[String, untyped] right) -> Hash[String, untyped]
+      def merge_syntax_fields(left, right)
+        left.to_h do |name, left_slot|
+          right_slot = right.fetch(name)
+          left_index = left_slot.is_a?(Hash) ? left_slot.fetch(:index) : left_slot
+          right_index = right_slot.is_a?(Hash) ? right_slot.fetch(:index) : right_slot
+          raise Ibex::Error, "inconsistent CST slot for #{name}" unless left_index == right_index
+
+          [name, left_slot == right_slot ? left_slot : left_index]
+        end.freeze
+      end
+
+      # @rbs (Array[String] lines, Hash[Symbol, untyped] definition) -> void
+      def append_syntax_node_contract(lines, definition)
+        name = definition.fetch(:name)
+        fields = definition.fetch(:fields)
+        lines.push(
+          "    class #{name} < Ibex::Runtime::CST::TypedNode",
+          "      KIND: Integer",
+          "      def self.cast: (Ibex::Runtime::CST::SyntaxNode node) -> #{name}?"
+        )
+        fields.each_with_index do |(field, _slot), index|
+          lines << "      def #{field}: () -> #{syntax_field_type(name, index)}"
+        end
+        append_repetition_contracts(lines, fields)
+        lines << "    end"
+      end
+
+      # @rbs (String node_name, Integer index) -> String
+      def syntax_field_type(node_name, index)
+        symbol_ids = @grammar.productions.filter_map do |production|
+          production.rhs.fetch(index) if production.node&.fetch(:name) == node_name
+        end
+        types = symbol_ids.map do |symbol_id|
+          symbol = @grammar.symbols.fetch(symbol_id)
+          symbol.terminal? ? "Ibex::Runtime::CST::SyntaxToken" : "Ibex::Runtime::CST::SyntaxNode"
+        end.uniq
+        types.one? ? types.fetch(0) : "(#{types.join(' | ')})"
+      end
+
+      # @rbs (Array[String] lines, Hash[String, untyped] fields) -> void
+      def append_repetition_contracts(lines, fields)
+        repeated = fields.select { |_field, slot| slot.is_a?(Hash) && slot[:extraction] }
+        element = "Enumerator[Ibex::Runtime::CST::SyntaxNode | Ibex::Runtime::CST::SyntaxToken, void]"
+        repeated.each do |field, slot|
+          lines << "      def each_#{field}_element: () -> #{element}"
+          lines << "      def each_#{field}_separator: () -> #{element}" if slot.fetch(:extraction) == :separated_list
+        end
+        return unless repeated.one?
+
+        _field, slot = repeated.first
+        lines << "      def each_element: () -> #{element}"
+        lines << "      def each_separator: () -> #{element}" if slot.fetch(:extraction) == :separated_list
+      end
+
+      # @rbs () -> Hash[String, IR::node_annotation]
+      def ast_node_definitions
+        @grammar.productions.filter_map(&:node).to_h { |node| [node.fetch(:name), node] }
+      end
+
+      # @rbs (Array[String] lines, IR::node_annotation node) -> void
+      def append_ast_node_contract(lines, node)
+        name = node.fetch(:name)
+        fields = node.fetch(:fields)
+        types = ast_node_field_types(name, fields.length)
+        lines << "    class #{name} < Data"
+        fields.each_with_index { |field, index| lines << "      attr_reader #{field}: #{types.fetch(index)}" }
+        keywords = fields.each_with_index.map { |field, index| "#{field}: #{types.fetch(index)}" }
+        lines << "      def self.new: (#{keywords.join(', ')}) -> instance"
+        lines << "      def initialize: (#{keywords.join(', ')}) -> void"
+        lines << "    end"
+      end
+
+      # @rbs (String name, Integer length) -> Array[String]
+      def ast_node_field_types(name, length)
+        productions = @grammar.productions.select { |production| production.node&.fetch(:name) == name }
+        Array.new(length) do |index|
+          types = productions.map { |production| semantic_type(production.rhs.fetch(index)) }.uniq
+          types.length == 1 ? types.fetch(0) : "(#{types.join(' | ')})"
+        end
+      end
+
+      # @rbs (Array[String] lines, Hash[String, IR::node_annotation] definitions) -> void
+      def append_visitor_contract(lines, definitions)
+        lines.push("    class Visitor", "      def visit: (untyped node) -> untyped")
+        definitions.each_value do |node|
+          name = node.fetch(:name)
+          lines << "      def visit_#{ast_method_name(name)}: (#{name} node) -> untyped"
+        end
+        lines.push("      def visit_children: (untyped node) -> untyped", "    end")
+      end
+
+      # @rbs (Array[String] lines, Hash[String, IR::node_annotation] definitions) -> void
+      def append_listener_contract(lines, definitions)
+        lines.push("    class Listener", "      def walk: (untyped node) -> untyped",
+                   "      def enter: (untyped node) -> void", "      def exit: (untyped node) -> void")
+        definitions.each_value do |node|
+          name = node.fetch(:name)
+          method = ast_method_name(name)
+          lines << "      def enter_#{method}: (#{name} node) -> void"
+          lines << "      def exit_#{method}: (#{name} node) -> void"
+        end
+        lines.push("      def listener_children: (untyped node) -> Array[untyped]", "    end")
+      end
+
+      # @rbs (String name) -> String
+      def ast_method_name(name)
+        name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+      end
+
       # @rbs (Array[String] lines) -> void
       def append_contract(lines)
         lines.push("  PARSER_TABLE_FORMAT_VERSION: Integer",
+                   "  GRAMMAR_DIGEST: String", "  STATE_COUNT: Integer", "  PRODUCTION_COUNT: Integer",
                    "  TOKEN_IDS: Hash[untyped, Integer]", "  TOKEN_NAMES: Hash[Integer, String]",
                    "  ACTIONS: untyped", "  GOTOS: untyped", "  DEFAULT_ACTIONS: Array[untyped]",
+                   "  EAGER_REDUCTIONS: Hash[Integer, [:reduce, Integer]]",
                    "  PRODUCTIONS: Array[Hash[Symbol, untyped]]",
+                   "  ERROR_MESSAGES: Hash[Integer, String | { id: String, message: String }]",
                    "  PARSER_TABLES: Hash[Symbol, untyped]", "  DEBUG_ENABLED: bool", "",
                    "  def self.parser_tables: () -> Hash[Symbol, untyped]")
+        lines << "  SYMBOL_NAMES: Hash[Integer, String]" if @grammar.options[:cst] == true
+        lines << "  CST_METADATA: Hash[Symbol, untyped]" if @grammar.options[:cst] == true
+        lines << "  CST_KIND_MODEL: Ibex::Runtime::CST::Kind" if @grammar.options[:cst] == true
+        append_entry_contract(lines)
+        append_parameter_contract(lines)
+      end
+
+      # @rbs (Array[String] lines) -> void
+      def append_entry_contract(lines)
+        return unless @grammar.starts.length > 1
+
+        lines << "  ENTRY_STATES: Hash[Symbol, Integer]"
+        @grammar.starts.each { |name| lines << "  def parse_#{name}: () -> untyped" }
+      end
+
+      # @rbs (Array[String] lines) -> void
+      def append_parameter_contract(lines)
+        parameters = @grammar.parser_parameters
+        return if parameters.empty?
+
+        parameters.each do |parameter|
+          lines << "  @#{parameter[:name]}: #{parameter[:semantic_type] || 'untyped'}"
+        end
+        keywords = parameters.map do |parameter|
+          "#{parameter[:name]}: #{parameter[:semantic_type] || 'untyped'}"
+        end
+        lines << ""
+        lines << "  def initialize: (#{keywords.join(', ')}, **untyped) -> void"
+      end
+
+      # @rbs (Array[String] lines) -> void
+      def append_lexer_contract(lines)
+        lexer = @grammar.lexer
+        return unless lexer
+
+        lines.push(
+          "  LEXER_STATES: Array[String]",
+          "  LEXER_RULES_BY_STATE: Hash[Symbol, Array[Hash[Symbol, untyped]]]",
+          "",
+          "  def lex: (String | IO | Fiber source, ?file: String) -> self",
+          "  def parse: (String | IO | Fiber source, ?file: String) -> untyped",
+          "  def lexer_state: () -> Symbol",
+          "  def lexer_state=: (Symbol | String state) -> Symbol",
+          "  def next_token: () -> [untyped, untyped, Hash[Symbol, untyped]]"
+        )
+        if @grammar.options[:cst] == true
+          lines << "  def parse_with_syntax: (String | IO | Fiber source, ?file: String) -> " \
+                   "Ibex::Runtime::CST::ParseResult"
+        end
+        lexer.rules.each do |rule|
+          lines << "  private def _ibex_lexer_action_#{rule.id}: (String lexeme) -> untyped" if rule.action
+        end
+      end
+
+      # @rbs (Array[String] lines) -> void
+      def append_value_printer_signatures(lines)
+        @grammar.value_printers.each do |printer|
+          symbol = @grammar.symbol(printer[:symbol]) || raise(Ibex::Error, "missing printer symbol #{printer[:symbol]}")
+          lines << ""
+          lines << "  private def _ibex_value_printer_#{symbol.id}: " \
+                   "(#{symbol.semantic_type || 'untyped'} value) -> untyped"
+        end
+      end
+
+      # @rbs (Array[String] lines) -> void
+      def append_actions(lines)
+        actions = @grammar.productions.select { |production| action_method?(production) }
+        return if actions.empty?
+
+        lines << ""
+        actions.each do |production|
+          append_action_signature(lines, production)
+          append_composed_fragment_signatures(lines, production) if composed_action?(production)
+        end
+      end
+
+      # @rbs (Array[String] lines, IR::Production production) -> void
+      def append_action_signature(lines, production)
+        parameters = production.rhs.map { |symbol_id| semantic_type(symbol_id) }.join(", ")
+        result = production.node ? "AST::#{production.node.fetch(:name)}" : semantic_type(production.lhs)
+        if @generated_action_abi.positional_values?(production)
+          lines << "  private def _ibex_action_#{production.id}: (#{parameters}) -> #{result}"
+          return
+        end
+        if @generated_action_abi.values_only?(production)
+          lines << "  private def _ibex_action_#{production.id}: ([#{parameters}]) -> #{result}"
+          return
+        end
+
+        locations = Array.new(production.rhs.length, "untyped").join(", ")
+        lookahead = composed_action?(production) ? ", untyped" : ""
+        lines << "  private def _ibex_action_#{production.id}: " \
+                 "([#{parameters}], Array[untyped], [#{locations}], Array[untyped], " \
+                 "Ibex::Runtime::LocationSpan?#{lookahead}) -> #{result}"
+      end
+
+      # @rbs (Array[String] lines, IR::Production production) -> void
+      def append_composed_fragment_signatures(lines, production)
+        plan = production.action&.composition&.dig(:plan)
+        raise Ibex::Error, "missing action composition plan" unless plan
+
+        plan.fetch(:steps).each_with_index do |step, index|
+          next unless step[:code]
+
+          inputs = step.fetch(:inputs).map do |slot|
+            composition_slot_type(production, plan, slot, index)
+          end
+          locations = Array.new(inputs.length, "untyped").join(", ")
+          result = step[:result_type] || "untyped"
+          lines << "  private def _ibex_inline_fragment_#{production.id}_#{index}: " \
+                   "([#{inputs.join(', ')}], Array[untyped], [#{locations}], Array[untyped], " \
+                   "Ibex::Runtime::LocationSpan?) -> #{result}"
+        end
+      end
+
+      # @rbs (IR::Production production, Hash[Symbol, untyped] plan, Integer slot, Integer step_index) -> String
+      def composition_slot_type(production, plan, slot, step_index)
+        physical = plan.fetch(:physical)
+        return semantic_type(production.rhs.fetch(slot)) if slot < physical
+
+        prior_index = slot - physical
+        raise Ibex::Error, "invalid composed action slot #{slot}" if prior_index >= step_index
+
+        plan.fetch(:steps).fetch(prior_index)[:result_type] || "untyped"
+      end
+
+      # @rbs (IR::Production production) -> bool
+      def action_method?(production)
+        !!(production.node || production.action || !@omit_action_call)
+      end
+
+      # @rbs (IR::Production production) -> bool
+      def composed_action?(production)
+        production.action&.composition&.dig(:plan, :version) == 1
+      end
+
+      # @rbs (Integer symbol_id) -> String
+      def semantic_type(symbol_id)
+        symbol = @grammar.symbol_by_id(symbol_id) || raise(Ibex::Error, "missing grammar symbol id #{symbol_id}")
+        symbol.semantic_type || inferred_ast_type(symbol_id) || "untyped"
+      end
+
+      # @rbs (Integer symbol_id) -> String?
+      def inferred_ast_type(symbol_id)
+        productions = @grammar.productions.select { |production| production.lhs == symbol_id }
+        return if productions.empty? || productions.any? { |production| production.node.nil? }
+
+        names = productions.map { |production| production.node&.fetch(:name) }.compact.uniq
+        return if names.empty?
+
+        types = names.map { |name| "AST::#{name}" }
+        types.length == 1 ? types.fetch(0) : "(#{types.join(' | ')})"
       end
 
       # @rbs () -> [Array[String], String]
@@ -50,5 +370,6 @@ module Ibex
         @automaton.grammar_digest.delete_prefix("sha256:").chars.first(12).join
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end