ibex 0.1.0 → 0.3.0

data/lib/ibex/normalize/inline_validation.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Ibex
+  # Static validation and collection for rules eliminated by inline expansion.
+  module NormalizeInlineValidation
+    private
+
+    # @rbs () -> void
+    def gather_inline_rules
+      # @type self: Normalizer
+      @inline_rule_names = Set.new #: Set[String]
+      markings = {} #: Hash[String, bool]
+      @ast.rules.each do |rule|
+        previous = markings[rule.lhs]
+        if !previous.nil? && previous != rule.inline
+          fail_at(rule.loc, "rule #{rule.lhs} has both inline and ordinary definitions")
+        end
+        markings[rule.lhs] = rule.inline
+        @inline_rule_names << rule.lhs if rule.inline
+      end
+      validate_inline_terminal_collisions
+      validate_inline_start
+      validate_inline_cycles
+    end
+
+    # @rbs () -> void
+    def validate_inline_terminal_collisions
+      # @type self: Normalizer
+      @ast.rules.each do |rule|
+        next unless rule.inline
+        next unless @declared_tokens.key?(rule.lhs) || @precedence.key?(rule.lhs)
+
+        fail_at(rule.loc, "inline rule #{rule.lhs} collides with terminal #{rule.lhs}")
+      end
+    end
+
+    # @rbs () -> void
+    def validate_inline_start
+      # @type self: Normalizer
+      inline_start = @explicit_starts&.find { |name| @inline_rule_names.include?(name) }
+      return unless inline_start
+
+      fail_at(@start_location || @ast.loc, "inline rule #{inline_start} cannot be the start symbol")
+    end
+
+    # @rbs () -> void
+    def validate_inline_cycles
+      # @type self: Normalizer
+      names = @ast.rules.to_set(&:lhs)
+      liveness = parameter_formal_liveness
+      graph = Hash.new { |hash, name| hash[name] = [] } #: Hash[String, Array[[String, Frontend::Location]]]
+      @ast.rules.each do |rule|
+        rule.alternatives.each do |alternative|
+          alternative.items.each do |item|
+            collect_inline_edges(item, rule.parameters, names, graph[rule.lhs], liveness)
+          end
+        end
+      end
+      states = {} #: Hash[String, Symbol]
+      names.each { |name| visit_inline_cycle(name, graph, states) unless states.key?(name) }
+    end
+
+    # A formal is live for cycle analysis only when substituting its actual can
+    # introduce a grammar reference. Calls propagate liveness through their
+    # callee's live positions until the finite formal set reaches a fixed point.
+    # @rbs () -> Hash[String, Set[Integer]]
+    def parameter_formal_liveness
+      # @type self: Normalizer
+      liveness = @parameter_formals.to_h { |name, _formals| [name, Set.new] } #: Hash[String, Set[Integer]]
+      loop do
+        changed = false
+        @parameter_templates.each do |name, rules|
+          formals = @parameter_formals.fetch(name)
+          found = Set.new #: Set[Integer]
+          rules.each do |rule|
+            rule.alternatives.each do |alternative|
+              alternative.items.each { |item| collect_live_formals(item, formals, liveness, found) }
+            end
+          end
+          additions = found - liveness.fetch(name)
+          next if additions.empty?
+
+          liveness.fetch(name).merge(additions)
+          changed = true
+        end
+        return liveness unless changed
+      end
+    end
+
+    # @rbs (Frontend::AST::item item, Array[String] formals,
+    #   Hash[String, Set[Integer]] liveness, Set[Integer] found) -> void
+    def collect_live_formals(item, formals, liveness, found)
+      # @type self: Normalizer
+      case item
+      when Frontend::AST::SymbolReference
+        index = formals.index(item.name)
+        found << index if index
+      when Frontend::AST::ParameterizedReference
+        liveness.fetch(item.name, Set.new).each do |index|
+          collect_live_formals(item.arguments.fetch(index), formals, liveness, found)
+        end
+      when Frontend::AST::Group
+        item.alternatives.flatten.each { |child| collect_live_formals(child, formals, liveness, found) }
+      when Frontend::AST::Optional, Frontend::AST::Star, Frontend::AST::Plus
+        collect_live_formals(item.item, formals, liveness, found)
+      when Frontend::AST::SeparatedList
+        collect_live_formals(item.item, formals, liveness, found)
+        collect_live_formals(item.separator, formals, liveness, found)
+      end
+    end
+
+    # Structural AST traversal necessarily branches once for each public item shape.
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # @rbs (Frontend::AST::item item, Array[String] formals, Set[String] names,
+    #   Array[[String, Frontend::Location]] edges, Hash[String, Set[Integer]] liveness) -> void
+    def collect_inline_edges(item, formals, names, edges, liveness)
+      # @type self: Normalizer
+      case item
+      when Frontend::AST::SymbolReference
+        edges << [item.name, item.loc] if !formals.include?(item.name) && names.include?(item.name)
+      when Frontend::AST::ParameterizedReference
+        edges << [item.name, item.loc] if names.include?(item.name)
+        liveness.fetch(item.name, Set.new).each do |index|
+          collect_inline_edges(item.arguments.fetch(index), formals, names, edges, liveness)
+        end
+      when Frontend::AST::Group
+        item.alternatives.flatten.each do |child|
+          collect_inline_edges(child, formals, names, edges, liveness)
+        end
+      when Frontend::AST::Optional, Frontend::AST::Star, Frontend::AST::Plus
+        collect_inline_edges(item.item, formals, names, edges, liveness)
+      when Frontend::AST::SeparatedList
+        collect_inline_edges(item.item, formals, names, edges, liveness)
+        collect_inline_edges(item.separator, formals, names, edges, liveness)
+      end
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    # @rbs (String name, Hash[String, Array[[String, Frontend::Location]]] graph,
+    #   Hash[String, Symbol] states) -> void
+    def visit_inline_cycle(name, graph, states)
+      # @type self: Normalizer
+      states[name] = :visiting
+      path = [name] #: Array[String]
+      positions = { name => 0 } #: Hash[String, Integer]
+      worklist = [[name, 0]] #: Array[[String, Integer]]
+      until worklist.empty?
+        current, edge_index = worklist.fetch(-1)
+        edges = graph[current]
+        if edge_index >= edges.length
+          worklist.pop
+          positions.delete(path.pop || raise(Ibex::Error, "internal inline cycle path underflow"))
+          states[current] = :visited
+          next
+        end
+
+        worklist[-1] = [current, edge_index + 1]
+        target, location = edges.fetch(edge_index)
+        if states[target] == :visiting
+          cycle = path.drop(positions.fetch(target))
+          next unless cycle.any? { |entry| @inline_rule_names.include?(entry) }
+
+          fail_at(location, "inline expansion cycle: #{(cycle + [target]).join(' -> ')}")
+        end
+        next if states.key?(target)
+
+        states[target] = :visiting
+        positions[target] = path.length
+        path << target
+        worklist << [target, 0]
+      end
+    end
+  end
+end

data/lib/ibex/normalize/lexer.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Ibex
+  # Lexer declaration normalization and static safety checks.
+  module NormalizeLexer
+    private
+
+    # @rbs () -> IR::Lexer?
+    def normalize_lexer
+      # @type self: Normalizer
+      declaration = @lexer_declaration
+      return unless declaration
+
+      states = ["INITIAL"] #: Array[String]
+      rules = [] #: Array[IR::LexerRule]
+      warnings = [] #: Array[IR::lexer_warning]
+      declaration.definitions.each do |definition|
+        if definition.is_a?(Frontend::AST::LexerState)
+          normalize_lexer_state(definition, states, rules, warnings)
+        else
+          rules << normalize_lexer_rule(definition, "INITIAL", rules.length, warnings)
+        end
+      end
+      fail_at(declaration.loc, "lexer declaration requires at least one rule") if rules.empty?
+      IR::Lexer.new(
+        states: states, rules: rules, warnings: warnings,
+        source_provenance: { file: declaration.loc.file, root: @resolution&.root_directory, byte_span: nil }
+      )
+    end
+
+    # @rbs (Frontend::AST::LexerState definition, Array[String] states, Array[IR::LexerRule] rules,
+    #   Array[IR::lexer_warning] warnings) -> void
+    def normalize_lexer_state(definition, states, rules, warnings)
+      # @type self: Normalizer
+      fail_at(definition.loc, "lexer state INITIAL is reserved") if definition.name == "INITIAL"
+      fail_at(definition.loc, "duplicate lexer state #{definition.name}") if states.include?(definition.name)
+      states << definition.name
+      definition.definitions.each do |entry|
+        fail_at(entry.loc, "nested lexer states are not supported") if entry.is_a?(Frontend::AST::LexerState)
+
+        rules << normalize_lexer_rule(entry, definition.name, rules.length, warnings)
+      end
+    end
+
+    # @rbs (Frontend::AST::LexerRule definition, String state, Integer id,
+    #   Array[IR::lexer_warning] warnings) -> IR::LexerRule
+    def normalize_lexer_rule(definition, state, id, warnings)
+      # @type self: Normalizer
+      validate_lexer_token(definition)
+      validate_lexer_action(definition)
+      source, options = normalize_lexer_pattern(definition)
+      validate_lexer_regexp(definition, source, options)
+      if risky_lexer_pattern?(source)
+        warning = { type: :lexer_redos, loc: definition.loc.to_h } #: IR::grammar_warning
+        warning[:symbol] = definition.token if definition.token
+        @warnings << warning
+        warnings << { type: :redos, rule: id, loc: definition.loc.to_h }
+      end
+      IR::LexerRule.new(
+        id: id, state: state, kind: definition.kind, token: definition.token,
+        pattern: source, pattern_kind: definition.pattern_kind, options: options,
+        action: definition.action, location: definition.loc.to_h
+      )
+    end
+
+    # @rbs (Frontend::AST::LexerRule definition) -> void
+    def validate_lexer_token(definition)
+      # @type self: Normalizer
+      return unless definition.kind == :token
+      return if definition.token && @declared_tokens.key?(definition.token)
+
+      fail_at(definition.loc, "lexer rule references undeclared terminal #{definition.token}")
+    end
+
+    # @rbs (Frontend::AST::LexerRule definition) -> void
+    def validate_lexer_action(definition)
+      # @type self: Normalizer
+      action = definition.action
+      return unless action&.lstrip&.start_with?("|")
+
+      match = action.match(/\A\s*\|([a-z_][a-zA-Z0-9_]*)\|/m)
+      fail_at(definition.loc, "lexer action accepts exactly one local identifier") unless match
+      name = match[1]
+      fail_at(definition.loc, "lexer action parameter #{name.inspect} is a Ruby keyword") if
+        Normalizer::RUBY_KEYWORDS.include?(name)
+    end
+
+    # @rbs (Frontend::AST::LexerRule definition) -> [String, String]
+    def normalize_lexer_pattern(definition)
+      # @type self: Normalizer
+      raw = definition.pattern
+      if definition.pattern_kind == :literal
+        decoded = decode_lexer_literal(raw, definition.loc)
+        fail_at(definition.loc, "lexer pattern must not be empty") if decoded.empty?
+        return [Regexp.escape(decoded), ""]
+      end
+
+      closing = raw.rindex("/")
+      fail_at(definition.loc, "invalid lexer regular expression") unless closing&.positive?
+      [raw[1...closing] || "", raw[(closing + 1)..] || ""]
+    end
+
+    # @rbs (String raw, Frontend::Location location) -> String
+    def decode_lexer_literal(raw, location)
+      # @type self: Normalizer
+      return raw.undump if raw.start_with?('"')
+
+      (raw[1...-1] || "").gsub("\\'", "'").gsub("\\\\", "\\")
+    rescue RuntimeError => e
+      fail_at(location, "invalid lexer literal: #{e.message}")
+    end
+
+    # @rbs (Frontend::AST::LexerRule definition, String source, String options) -> void
+    def validate_lexer_regexp(definition, source, options)
+      # @type self: Normalizer
+      flags = 0
+      flags |= Regexp::IGNORECASE if options.include?("i")
+      flags |= Regexp::MULTILINE if options.include?("m")
+      flags |= Regexp::EXTENDED if options.include?("x")
+      regexp = Regexp.new("\\A(?:#{source})", flags)
+      fail_at(definition.loc, "lexer pattern must not match an empty string") if regexp.match?("")
+    rescue RegexpError => e
+      fail_at(definition.loc, "invalid lexer regular expression: #{e.message}")
+    end
+
+    # @rbs (String source) -> bool
+    def risky_lexer_pattern?(source)
+      source.match?(/\([^)]*[+*][^)]*\)[+*{]/) || source.match?(/\.\*[+*{]/)
+    end
+  end
+end

data/lib/ibex/normalize/named_references.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ibex
+  # Named-reference collection and validation shared by ordinary and parameterized items.
+  module NormalizeNamedReferences
+    private
+
+    # @rbs (Frontend::AST::Group group) -> void
+    def reject_group_named_references(group)
+      # @type self: Normalizer
+      reference = group.alternatives.flatten.filter_map { |item| named_reference_in(item) }.first
+      fail_at(reference.loc, "named references inside EBNF groups are not supported") if reference
+    end
+
+    # @rbs (Frontend::AST::item item) -> (Frontend::AST::SymbolReference | Frontend::AST::ParameterizedReference)?
+    def named_reference_in(item)
+      # @type self: Normalizer
+      if (item.is_a?(Frontend::AST::SymbolReference) ||
+          item.is_a?(Frontend::AST::ParameterizedReference)) && item.named_reference
+        return item
+      end
+      if item.is_a?(Frontend::AST::Group)
+        return item.alternatives.flatten.filter_map { |child| named_reference_in(child) }.first
+      end
+      if item.is_a?(Frontend::AST::Optional) || item.is_a?(Frontend::AST::Star) ||
+         item.is_a?(Frontend::AST::Plus) || item.is_a?(Frontend::AST::SeparatedList)
+        return named_reference_in(item.item)
+      end
+
+      nil
+    end
+
+    # @rbs (Frontend::AST::item item, Array[IR::named_ref] refs, Integer index) -> void
+    def add_named_reference(item, refs, index)
+      # @type self: Normalizer
+      reference = unwrap_reference(item)
+      return unless reference
+
+      name = reference.named_reference
+      return unless name
+
+      fail_at(reference.loc, "reserved named reference #{name}") if Normalizer::RESERVED_NAMES.include?(name)
+      fail_at(reference.loc, "duplicate named reference #{name}") if refs.any? { |entry| entry[:name] == name }
+      refs << { name: name, index: index }
+    end
+
+    # @rbs (Frontend::AST::item item) -> (Frontend::AST::SymbolReference | Frontend::AST::ParameterizedReference)?
+    def unwrap_reference(item)
+      # @type self: Normalizer
+      return item if item.is_a?(Frontend::AST::SymbolReference) ||
+                     item.is_a?(Frontend::AST::ParameterizedReference)
+      if item.is_a?(Frontend::AST::Optional) || item.is_a?(Frontend::AST::Star) ||
+         item.is_a?(Frontend::AST::Plus) || item.is_a?(Frontend::AST::SeparatedList)
+        return unwrap_reference(item.item)
+      end
+
+      nil
+    end
+  end
+end

data/lib/ibex/normalize/nodes.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ibex
+  # Validation and normalization for generated AST node declarations.
+  module NormalizeNodes
+    private
+
+    # @rbs (Frontend::AST::Alternative alternative, Array[String] rhs) -> IR::node_annotation?
+    def normalize_node_annotation(alternative, rhs)
+      # @type self: Normalizer
+      annotation = alternative.node_annotation
+      return unless annotation
+
+      if alternative.action || alternative.items.any?(Frontend::AST::InlineAction)
+        fail_at(annotation.loc, "@node cannot be combined with semantic actions")
+      end
+      unless annotation.name.match?(/\A[A-Z][A-Za-z0-9_]*\z/)
+        fail_at(annotation.loc, "@node name #{annotation.name.inspect} must be a Ruby constant identifier")
+      end
+      validate_node_fields(annotation, rhs)
+      previous = @node_shapes[annotation.name]
+      if previous && previous != annotation.fields
+        fail_at(annotation.loc, "@node #{annotation.name} was already declared with fields (#{previous.join(', ')})")
+      end
+      @node_shapes[annotation.name] = annotation.fields.dup.freeze
+      { name: annotation.name, fields: annotation.fields, loc: annotation.loc.to_h }
+    end
+
+    # @rbs (Frontend::AST::NodeAnnotation annotation, Array[String] rhs) -> void
+    def validate_node_fields(annotation, rhs)
+      # @type self: Normalizer
+      unless annotation.fields.length == rhs.length
+        fail_at(
+          annotation.loc,
+          "@node #{annotation.name} declares #{annotation.fields.length} fields for #{rhs.length} RHS values"
+        )
+      end
+      duplicate = annotation.fields.tally.find { |_name, count| count > 1 }&.first
+      fail_at(annotation.loc, "@node field #{duplicate.inspect} is duplicated") if duplicate
+      invalid = annotation.fields.find do |field|
+        !field.match?(/\A[a-z_][a-zA-Z0-9_]*\z/) || Normalizer::RUBY_KEYWORDS.include?(field)
+      end
+      fail_at(annotation.loc, "@node field #{invalid.inspect} must be a Ruby local identifier") if invalid
+    end
+  end
+end

data/lib/ibex/normalize/parameter_ebnf_lowering.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Ibex
+  # Resumable EBNF lowering used inside specialized parameter alternatives.
+  module NormalizeParameterEbnfLowering
+    private
+
+    # @rbs (NormalizeParameters::parameter_frame frame,
+    #   Frontend::AST::Optional | Frontend::AST::Star | Frontend::AST::Plus item) -> void
+    def lower_parameter_suffix(frame, item)
+      frame.fetch(:operations).push([:finish_suffix, item], [:item, item.item])
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame,
+    #   Frontend::AST::Optional | Frontend::AST::Star | Frontend::AST::Plus item) -> void
+    def finish_parameter_suffix(frame, item)
+      # @type self: Normalizer
+      base = frame.fetch(:values).pop || raise(Ibex::Error, "missing parameter value")
+      helper = case item
+               when Frontend::AST::Optional then build_optional(item, base)
+               when Frontend::AST::Star then build_star(item, base)
+               when Frontend::AST::Plus then build_plus(item, base)
+               end
+      frame.fetch(:values) << helper
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, Frontend::AST::SeparatedList item) -> void
+    def lower_parameter_separated_list(frame, item)
+      frame.fetch(:operations).push(
+        [:finish_separated, item], [:item, item.separator], [:item, item.item]
+      )
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, Frontend::AST::SeparatedList item) -> void
+    def finish_parameter_separated_list(frame, item)
+      # @type self: Normalizer
+      separator = frame.fetch(:values).pop || raise(Ibex::Error, "missing parameter value")
+      base = frame.fetch(:values).pop || raise(Ibex::Error, "missing parameter value")
+      frame.fetch(:values) << build_separated_list(item, base, separator)
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, Frontend::AST::Group item) -> void
+    def lower_parameter_group(frame, item)
+      # @type self: Normalizer
+      reject_group_named_references(item)
+      helper = new_helper("group", item.loc)
+      operations = frame.fetch(:operations)
+      operations << [:value, helper]
+      item.alternatives.reverse_each do |alternative|
+        operations << [:group_alternative, helper, item, alternative]
+      end
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, String helper, Frontend::AST::Group item,
+    #   Array[Frontend::AST::item] alternative) -> void
+    def start_parameter_group_alternative(frame, helper, item, alternative)
+      operations = frame.fetch(:operations)
+      operations << [:finish_group_alternative, helper, item, alternative.length]
+      alternative.reverse_each { |child| operations << [:item, child] }
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, String helper,
+    #   Frontend::AST::Group item, Integer length) -> void
+    def finish_parameter_group_alternative(frame, helper, item, length)
+      # @type self: Normalizer
+      rhs = frame.fetch(:values).pop(length)
+      add_group_production(helper, rhs, item)
+    end
+  end
+end

data/lib/ibex/normalize/parameter_lowering.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Ibex
+  # Resumable, source-ordered lowering for specialized parameter alternatives.
+  module NormalizeParameterLowering
+    private
+
+    # @rbs (NormalizeParameters::parameter_frame frame) -> void
+    def advance_parameter_alternative(frame)
+      # @type self: Normalizer
+      with_parameter_frame_context(frame) do
+        operations = frame.fetch(:operations)
+        if operations.any?
+          operation = operations.pop #: NormalizeParameters::parameter_operation
+          process_parameter_operation(frame, operation)
+        elsif parameter_items_remaining?(frame)
+          start_parameter_item(frame)
+        else
+          finish_parameter_alternative(frame)
+        end
+      end
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame) { () -> void } -> void
+    def with_parameter_frame_context(frame)
+      # @type self: Normalizer
+      template, = frame.fetch(:current) || raise(Ibex::Error, "missing parameter alternative")
+      previous_chain = @current_include_chain
+      previous_expansion = @current_parameter_expansion
+      reference = frame.fetch(:reference)
+      @current_include_chain = @resolution&.include_chain_for(template) || []
+      @current_parameter_expansion = {
+        rule: reference.name, arguments: frame.fetch(:rendered_arguments)
+      }
+      yield
+    ensure
+      @current_include_chain = previous_chain
+      @current_parameter_expansion = previous_expansion
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame) -> bool
+    def parameter_items_remaining?(frame)
+      _template, _rule, alternative = frame.fetch(:current) || raise(Ibex::Error, "missing parameter alternative")
+      frame.fetch(:item_index) < alternative.items.length
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame) -> void
+    def start_parameter_item(frame)
+      # @type self: Normalizer
+      _template, _rule, alternative = frame.fetch(:current) || raise(Ibex::Error, "missing parameter alternative")
+      index = frame.fetch(:item_index)
+      item = alternative.items.fetch(index)
+      frame[:item_index] = index + 1
+      if item.is_a?(Frontend::AST::InlineAction)
+        frame.fetch(:rhs) << expand_inline_action(
+          item, frame.fetch(:rhs).length, frame.fetch(:named_refs)
+        )
+      else
+        frame.fetch(:operations).push([:finish_item, item], [:item, item])
+      end
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, NormalizeParameters::parameter_operation operation) -> void
+    def process_parameter_operation(frame, operation)
+      # @type self: Normalizer
+      kind = operation.fetch(0) #: Symbol
+      case kind
+      when :item
+        item = operation.fetch(1) #: Frontend::AST::item
+        lower_parameter_item(frame, item)
+      when :finish_item
+        item = operation.fetch(1) #: Frontend::AST::item
+        finish_parameter_item(frame, item)
+      when :value
+        value = operation.fetch(1) #: String
+        frame.fetch(:values) << value
+      when :finish_suffix
+        item = operation.fetch(1) #: Frontend::AST::Optional | Frontend::AST::Star | Frontend::AST::Plus
+        finish_parameter_suffix(frame, item)
+      when :finish_separated
+        item = operation.fetch(1) #: Frontend::AST::SeparatedList
+        finish_parameter_separated_list(frame, item)
+      when :group_alternative
+        helper = operation.fetch(1) #: String
+        item = operation.fetch(2) #: Frontend::AST::Group
+        alternative = operation.fetch(3) #: Array[Frontend::AST::item]
+        start_parameter_group_alternative(frame, helper, item, alternative)
+      when :finish_group_alternative
+        helper = operation.fetch(1) #: String
+        item = operation.fetch(2) #: Frontend::AST::Group
+        length = operation.fetch(3) #: Integer
+        finish_parameter_group_alternative(frame, helper, item, length)
+      else raise Ibex::Error, "internal parameter lowering operation #{kind.inspect}"
+      end
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, Frontend::AST::item item) -> void
+    def lower_parameter_item(frame, item)
+      # @type self: Normalizer
+      case item
+      when Frontend::AST::SymbolReference
+        frame.fetch(:values) << symbol_for_reference(item).name
+      when Frontend::AST::ParameterizedReference
+        lower_parameter_call(frame, item)
+      when Frontend::AST::Group
+        lower_parameter_group(frame, item)
+      when Frontend::AST::Optional, Frontend::AST::Star, Frontend::AST::Plus
+        lower_parameter_suffix(frame, item)
+      when Frontend::AST::SeparatedList
+        lower_parameter_separated_list(frame, item)
+      else
+        fail_at(item.loc, "unsupported nested EBNF expression")
+      end
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, Frontend::AST::ParameterizedReference item) -> void
+    def lower_parameter_call(frame, item)
+      # @type self: Normalizer
+      helper, = schedule_parameter_specialization(item)
+      frame.fetch(:values) << helper
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame, Frontend::AST::item item) -> void
+    def finish_parameter_item(frame, item)
+      # @type self: Normalizer
+      rhs = frame.fetch(:rhs)
+      rhs << (frame.fetch(:values).pop || raise(Ibex::Error, "missing parameter value"))
+      add_named_reference(item, frame.fetch(:named_refs), rhs.length - 1)
+    end
+
+    # @rbs (NormalizeParameters::parameter_frame frame) -> void
+    def finish_parameter_alternative(frame)
+      # @type self: Normalizer
+      _template, rule, alternative = frame.fetch(:current) || raise(Ibex::Error, "missing parameter alternative")
+      action = normalize_action(alternative.action, frame.fetch(:named_refs))
+      add_production(
+        rule.lhs, frame.fetch(:rhs), action, alternative.precedence,
+        { kind: :user, loc: alternative.loc.to_h }, rule.documentation
+      )
+      clear_parameter_alternative(frame)
+    end
+  end
+end