ast_transform 2.1.4 → 3.1.0

data/lib/ast_transform/instruction_sequence.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module ASTTransform
   module InstructionSequence
     class << self
@@ -22,12 +23,12 @@ module ASTTransform
       def write_pathname(file_path)
         project_path = File.expand_path("")
         relative_source_file_pathname = Pathname.new(file_path).relative_path_from(Pathname.new(project_path))
-        Pathname.new("").join(project_path, 'tmp', 'ast_transform', relative_source_file_pathname)
+        Pathname.new("").join(project_path, "tmp", "ast_transform", relative_source_file_pathname)
       end
 
       def write(string, pathname)
         FileUtils.mkdir_p(pathname.dirname)
-        File.open(pathname, 'w') do |file|
+        File.open(pathname, "w") do |file|
           file.write(string)
         end
       end

data/lib/ast_transform/kwargs_builder.rb

@@ -1,22 +1,23 @@
 # frozen_string_literal: true
 
-require 'prism/translation/parser'
+require "prism/translation/parser"
 
 module ASTTransform
-  # Extends the default Prism parser builder to distinguish keyword arguments
-  # from hash literals in the AST.
+  # The framework's parser builder: the stock builder with the parser gem's `emit_kwargs` opt-in, which
+  # distinguishes keyword arguments from hash literals in the AST.
   #
-  # The upstream builder always emits :hash nodes for both `foo(bar: 1)` and
-  # `foo({ bar: 1 })`. Unparser uses the node type to decide whether to emit
-  # braces: :hash gets `{}`, :kwargs does not. Since Ruby 3.0+ treats these as
-  # semantically different (strict keyword/positional separation), we need the
-  # AST to preserve the distinction.
+  # With the flag off (the gem's compatibility default) both `foo(bar: 1)` and `foo({ bar: 1 })` emit :hash nodes.
+  # Unparser uses the node type to decide whether to emit braces: :hash gets `{}`, :kwargs does not. Since Ruby 3.0+
+  # treats these as semantically different (strict keyword/positional separation), the AST must preserve the
+  # distinction. `emit_kwargs` rewrites at the call sites where kwargs semantics live (method calls, index,
+  # super/yield); the flag is a class-level ivar, so setting it here opts in this builder only — the global
+  # Parser::Builders::Default stays untouched.
+  #
+  # NOTE: parsed nodes deliberately stay plain Parser::AST::Node. Custom node classes exist only for registered
+  # custom types (see ASTTransform::Node), which are IR and never reach Unparser: AST::Node#eql? compares class, and
+  # Unparser verifies dynamic-string emission by re-parsing and comparing eql? against the freshly parsed
+  # (plain-class) node — custom-class nodes of standard types would fail that verification.
   class KwargsBuilder < Prism::Translation::Parser::Builder
-    def associate(begin_t, pairs, end_t)
-      node = super
-      return node unless begin_t.nil? && end_t.nil?
-
-      node.updated(:kwargs)
-    end
+    self.emit_kwargs = true
   end
 end

data/lib/ast_transform/layout.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ASTTransform
+  # Line-addressed output: text is placed at absolute line numbers, top to bottom, and the cursor never rewinds.
+  # When a placement's target line is already behind the cursor, the text is packed (`; `) onto the current line
+  # instead — Ruby lets statements share a physical line, so alignment degrades locally and the next placement
+  # whose target is still ahead re-anchors. Knows nothing about Ruby structure or ASTs; callers decide WHAT goes
+  # on WHICH line, the layout owns the pad-or-pack mechanics.
+  class Layout
+    def initialize
+      @lines = []
+    end
+
+    # The line number currently being written; the next fresh line would be +cursor + 1+.
+    def cursor
+      @lines.size
+    end
+
+    # Places +text+ at +target_line+ when the cursor hasn't passed it; otherwise packs onto the current line.
+    # Multi-line text advances the cursor by its height. When opening a fresh line, the first line is indented to
+    # +column+ — cosmetic only (leading whitespace is never significant in emitted code), but it keeps the artifact
+    # visually close to the source. Packed text ignores the column, as do continuation lines (they keep their own
+    # relative indentation).
+    def place(target_line, text, column: nil)
+      first, *rest = text.split("\n")
+
+      if target_line && target_line > @lines.size
+        @lines << '' while @lines.size < target_line
+        @lines[-1] = indented(first, column)
+      else
+        pack(first)
+      end
+
+      @lines.concat(rest)
+    end
+
+    # Appends +text+ on a new line unconditionally — for text that must never be `;`-packed after a statement
+    # (e.g. keywords).
+    def place_on_fresh_line(text)
+      @lines << text
+    end
+
+    # Appends +text+ to the current line with a `; ` separator. The last line is never blank here: padding blanks
+    # are only created inside +place+, which immediately overwrites the padded line.
+    def pack(text)
+      if @lines.empty?
+        @lines << text
+      else
+        @lines[-1] = "#{@lines.last}; #{text}"
+      end
+    end
+
+    # @return [String] the laid-out text, with a trailing newline.
+    def to_source
+      "#{@lines.join("\n")}\n"
+    end
+
+    private
+
+    def indented(text, column)
+      column && column.positive? ? "#{' ' * column}#{text}" : text
+    end
+  end
+end

data/lib/ast_transform/line_aligned_emitter.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'ast_transform/node'
+require 'ast_transform/layout'
+require 'ast_transform/statement_renderer'
+require 'ast_transform/thunk_lowering'
+
+module ASTTransform
+  # Emits a transformed AST as text in which every loc-carrying statement occupies its original source line, so that
+  # backtraces, breakpoints and debugger display are correct by construction — CRuby derives line numbers from
+  # physical text position, so placement is our line table.
+  #
+  # Placement policy over statement sequences:
+  #
+  # 1. Statement has loc: target its source line — the Layout pads to reach it, or packs (`; `) when the cursor has
+  #    already passed it. A user statement packing means the transform moved it — the alignment auditor's concern,
+  #    not a runtime failure.
+  # 2. No loc: pack onto the current line — synthetic code has no source-line truth to preserve.
+  #
+  # The emitter owns the Ruby knowledge: walking statement structure, deciding which line each node targets, and
+  # that keywords can never be `;`-packed. The pad-or-pack mechanics live in Layout; statement-to-text rendering
+  # (and its isolation workarounds) in StatementRenderer — both created per emission, so the emitter itself is
+  # stateless and an instance is a reusable collaborator.
+  #
+  # Thunk nodes are lowered (ThunkLowering) before layout; the emitter's postcondition is that no custom node type
+  # (ast_* markers or types registered on ASTTransform::Node) crosses the unparse boundary — they are IR between
+  # stages that understand them.
+  class LineAlignedEmitter
+    # Raised as the emitter's postcondition when a custom node type (ast_* markers or types registered on
+    # ASTTransform::Node) reaches the unparse boundary instead of being lowered by the stage that understands it.
+    class UnloweredNodeTypeError < StandardError; end
+
+    # Containers the emitter recurses into so nested statements align; every other node renders as an Unparser blob
+    # at its head line.
+    RECURSIVE_CONTAINER_TYPES = [:class, :module, :sclass, :def, :defs, :block, :numblock, :itblock, :kwbegin].freeze
+    BODY_INDEXES = {
+      class: 2, module: 1, sclass: 1, def: 2, defs: 3, block: 2, numblock: 2, itblock: 2
+    }.freeze
+    # Assignments whose value is a block (e.g. the lowered thunk proc) recurse into the block so its body statements
+    # align.
+    ASSIGNMENT_TYPES = [:lvasgn, :ivasgn, :gvasgn, :casgn].freeze
+    BLOCK_VALUE_TYPES = [:block, :numblock, :itblock].freeze
+
+    # @param thunk_lowering [ThunkLowering] the lowering run ahead of emission.
+    def initialize(thunk_lowering: ThunkLowering.new)
+      @thunk_lowering = thunk_lowering
+    end
+
+    # @param ast [Parser::AST::Node] transformed AST
+    # @param source_path [String] original file path (for error messages)
+    # @return [String] transformed source, line-aligned
+    # @raise [ThunkLowering::PlacementError] if a thunk cannot be textually placed
+    # @raise [UnloweredNodeTypeError] if a custom node type survived to emission
+    def emit(ast, source_path)
+      lowered = @thunk_lowering.lower(ast)
+      assert_no_custom_types(lowered, source_path)
+
+      layout = Layout.new
+      renderer = StatementRenderer.for_tree(lowered)
+      emit_statements(statements_of(lowered), layout, renderer)
+      layout.to_source
+    end
+
+    private
+
+    def emit_statements(statements, layout, renderer)
+      statements.each { |statement| emit_statement(statement, layout, renderer) }
+    end
+
+    def emit_statement(node, layout, renderer)
+      if recursive_container?(node)
+        emit_container(node, layout, renderer)
+      else
+        layout.place(node.loc&.line, renderer.aligned_render(node), column: node.loc&.column)
+      end
+    end
+
+    # Emits a container body that may be a bare :ensure/:rescue node (their begin/end context comes from the
+    # surrounding def/block/kwbegin, so the keywords must be emitted inline, aligned like statements).
+    def emit_body(body, layout, renderer)
+      case body&.type
+      when :ensure then emit_ensure(body, layout, renderer)
+      when :rescue then emit_rescue(body, layout, renderer)
+      else emit_statements(statements_of(body), layout, renderer)
+      end
+    end
+
+    def emit_ensure(node, layout, renderer)
+      *body, ensurer = node.children
+      body.each { |statement| emit_body(statement, layout, renderer) }
+      place_keyword(layout, keyword_line(node), 'ensure', column: keyword_column(node))
+      emit_statements(statements_of(ensurer), layout, renderer)
+    end
+
+    def emit_rescue(node, layout, renderer)
+      body, *resbodies, else_body = node.children
+      emit_body(body, layout, renderer)
+      resbodies.each { |resbody| emit_resbody(resbody, layout, renderer) }
+      return if else_body.nil?
+
+      else_range = node.loc.else if node.loc.respond_to?(:else)
+      place_keyword(layout, else_range&.line, 'else', column: else_range&.column)
+      emit_statements(statements_of(else_body), layout, renderer)
+    end
+
+    def emit_resbody(node, layout, renderer)
+      exceptions, capture, body = node.children
+      header = ['rescue']
+      header << " #{renderer.unparse(exceptions).delete_prefix('[').delete_suffix(']')}" if exceptions
+      header << " => #{capture.children[0]}" if capture
+      place_keyword(layout, node.loc&.line, header.join, column: node.loc&.column)
+      emit_statements(statements_of(body), layout, renderer)
+    end
+
+    # Keywords (rescue/ensure/else) cannot be `;`-packed after a statement; when their line is taken they go on a
+    # fresh line instead.
+    def place_keyword(layout, target_line, keyword, column: nil)
+      if target_line && target_line > layout.cursor
+        layout.place(target_line, keyword, column: column)
+      else
+        layout.place_on_fresh_line(keyword)
+      end
+    end
+
+    def keyword_line(node)
+      loc = node.loc
+      loc.keyword.line if loc.respond_to?(:keyword) && loc.keyword
+    end
+
+    def keyword_column(node)
+      loc = node.loc
+      loc.keyword.column if loc.respond_to?(:keyword) && loc.keyword
+    end
+
+    def recursive_container?(node)
+      RECURSIVE_CONTAINER_TYPES.include?(node.type) || block_assignment?(node)
+    end
+
+    def block_assignment?(node)
+      ASSIGNMENT_TYPES.include?(node.type) && node.children.last.is_a?(::Parser::AST::Node) &&
+        BLOCK_VALUE_TYPES.include?(node.children.last.type)
+    end
+
+    # Renders a container's opener and closer from the node with its body emptied, then recurses into the body so
+    # nested statements align.
+    def emit_container(node, layout, renderer)
+      opener, closer = container_delimiters(node, renderer)
+      layout.place(node.loc&.line, opener, column: node.loc&.column)
+      emit_body(container_body(node), layout, renderer)
+      layout.place(closer_line(node), closer, column: closer_column(node))
+    end
+
+    def container_delimiters(node, renderer)
+      rendered = renderer.unparse(empty_container(node)).split("\n").reject(&:empty?)
+      opener = rendered[0..-2].join("\n")
+      closer = rendered.last
+
+      # Unparser renders empty blocks with braces, but brace blocks cannot hold rescue/ensure bodies; do/end always
+      # can.
+      if opener.end_with?(' {') && closer == '}'
+        [opener.sub(/ \{\z/, ' do'), 'end']
+      else
+        [opener, closer]
+      end
+    end
+
+    def empty_container(node)
+      case node.type
+      when :kwbegin
+        node.updated(nil, [])
+      when *ASSIGNMENT_TYPES
+        block_node = node.children.last
+        emptied_block = block_node.updated(nil, [*block_node.children[0..-2], nil])
+        node.updated(nil, [*node.children[0..-2], emptied_block])
+      else
+        children = node.children.dup
+        children[BODY_INDEXES.fetch(node.type)] = nil
+        node.updated(nil, children)
+      end
+    end
+
+    def container_body(node)
+      case node.type
+      when :kwbegin then node.children.size == 1 ? node.children.first : node.updated(:begin, node.children)
+      when *ASSIGNMENT_TYPES then node.children.last.children[2]
+      else node.children[BODY_INDEXES.fetch(node.type)]
+      end
+    end
+
+    # The line the container's `end`/`}` occupies in the source, when known.
+    def closer_line(node)
+      loc = node.loc
+      loc.end.line if loc.respond_to?(:end) && loc.end
+    end
+
+    def closer_column(node)
+      loc = node.loc
+      loc.end.column if loc.respond_to?(:end) && loc.end
+    end
+
+    # Loc-less :begin nodes in statement position (e.g. a lowered thunk in a single-statement container body, carried
+    # with its placement) are grouping, not structure: flatten them so each inner statement is laid out independently.
+    def statements_of(body)
+      return [] if body.nil?
+      return [body] unless body.type == :begin
+
+      body.children.flat_map do |child|
+        child.is_a?(::Parser::AST::Node) && child.type == :begin && child.loc.nil? ? statements_of(child) : [child]
+      end
+    end
+
+    def assert_no_custom_types(node, source_path)
+      return unless node.is_a?(::Parser::AST::Node)
+
+      if node.type.start_with?('ast_') || Node.registry.key?(node.type)
+        raise UnloweredNodeTypeError,
+          "custom node type :#{node.type} reached emission in #{source_path}; custom types are " \
+            "IR between transformation stages and must be lowered by the stage that understands them"
+      end
+
+      node.children.each { |child| assert_no_custom_types(child, source_path) }
+    end
+  end
+end

data/lib/ast_transform/node.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'parser'
+
+module ASTTransform
+  # Base class for custom IR nodes. Transform authors subclass it and register a custom node type to get type-routed
+  # construction from +s+ with domain accessors:
+  #
+  #   class InteractionNode < ASTTransform::Node
+  #     register :rspock_interaction
+  #
+  #     def cardinality = children[0]
+  #   end
+  #
+  #   s(:rspock_interaction, ...) # => InteractionNode
+  #
+  # Custom node *types* are IR between stages that understand them and must be lowered before emission (the emitter
+  # enforces this). Standard-typed nodes deliberately stay plain Parser::AST::Node everywhere — parsed and +s+-built
+  # alike: AST::Node#eql? compares class, and Unparser verifies dynamic-string emission by re-parsing and
+  # eql?-comparing, so a custom class on a standard type breaks emission.
+  class Node < ::Parser::AST::Node
+    class << self
+      # Registers +self+ as the class to construct for +type+ nodes.
+      #
+      # @param type [Symbol] the custom node type routed to this class
+      # @return [void]
+      def register(type)
+        Node.registry[type] = self
+      end
+
+      # Builds a node of +type+: registered types construct their custom class, everything else a plain
+      # Parser::AST::Node.
+      #
+      # @param type [Symbol] node type
+      # @param children [Array] child nodes / literals
+      # @param properties [Hash] node properties (e.g. location:)
+      # @return [Parser::AST::Node]
+      def build(type, children, properties = {})
+        klass = Node.registry.fetch(type, ::Parser::AST::Node)
+        klass.new(type, children, properties)
+      end
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/ast_transform/source_parser.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "prism"
+require "prism/translation/parser"
+require "ast_transform/kwargs_builder"
+
+module ASTTransform
+  # Owns source → AST parsing: Prism's C parser through its whitequark translation layer, so every consumer gets the
+  # node vocabulary Parser::AST::Processor understands. Transformer parses through this seam; analysis-only
+  # consumers that never emit instantiate it directly and keep the instance for as many parses as they need.
+  class SourceParser
+    # Constructs a new SourceParser instance.
+    #
+    # KwargsBuilder is a required implementation detail, not an injection seam: the framework's emission depends
+    # on the kwargs/hash distinction it preserves, so every parse goes through it.
+    def initialize
+      @builder = KwargsBuilder.new
+    end
+
+    # Parses the given +source+.
+    #
+    # @param source [String] The input source code.
+    # @param file_path [String] The file path recorded on source locations. This is important for source mapping
+    # in backtraces.
+    #
+    # @return [Parser::AST::Node] The AST.
+    def parse(source, file_path: "tmp")
+      # A fresh parser per parse: parser instances accumulate per-run state (lexer position, diagnostics), and
+      # constructing one is trivial next to the parse itself.
+      parser = Prism::Translation::Parser.new(@builder)
+      parser.parse(create_buffer(source, file_path, parser.default_encoding))
+    end
+
+    # Parses the source in the given +file_path+.
+    #
+    # @param file_path [String] The input file path.
+    #
+    # @return [Parser::AST::Node] The AST.
+    def parse_file(file_path)
+      parse(File.read(file_path), file_path: file_path)
+    end
+
+    private
+
+    # Builds a source buffer over +source+ in the given +encoding+.
+    #
+    # @param source [String] The input source code.
+    # @param file_path [String] The file path recorded on the buffer.
+    # @param encoding [Encoding] The encoding the buffer's source is coerced to.
+    #
+    # @return [Parser::Source::Buffer] The buffer.
+    def create_buffer(source, file_path, encoding)
+      buffer = Parser::Source::Buffer.new(file_path)
+      buffer.source = source.dup.force_encoding(encoding)
+
+      buffer
+    end
+  end
+end

data/lib/ast_transform/statement_renderer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'unparser'
+
+module ASTTransform
+  # Renders individual statements to text via Unparser, working around the two consequences of unparsing them in
+  # isolation (line-aligned emission places each statement independently, so each is ripped out of its context):
+  #
+  # * Isolation loses the surrounding scope's local variables, making Unparser re-parse identifiers as method calls
+  #   and fail its dstr round-trip verification — so a renderer is built once per tree with every local bound
+  #   anywhere in it, and feeds Unparser that set on each render.
+  # * Unparser normalizes some single-line constructs into multi-line form, which would push following statements
+  #   off their lines — so renders taller than their source are compressed back to one line when safely possible.
+  #
+  # Immutable: configured with the tree's locals at construction, no per-render state.
+  class StatementRenderer
+    # Node types that bind a local variable name: assignments plus every method/block parameter flavor.
+    LOCAL_BINDING_TYPES = [:lvasgn, :arg, :optarg, :restarg, :kwarg, :kwoptarg, :blockarg, :shadowarg].freeze
+
+    class << self
+      # Builds a renderer for statements of +node+'s tree, holding every local bound anywhere in it — an
+      # over-approximation that is safe because the set only informs Unparser's re-parse verification, never the
+      # rendered text.
+      def for_tree(node)
+        new(local_variables: collect_local_variables(node))
+      end
+
+      private
+
+      def collect_local_variables(node, names = Set.new)
+        return names unless node.is_a?(::Parser::AST::Node)
+
+        names << node.children[0] if LOCAL_BINDING_TYPES.include?(node.type) && node.children[0]
+        node.children.each { |child| collect_local_variables(child, names) }
+        names
+      end
+    end
+
+    # @param local_variables [Set<Symbol>] every local bound in the tree the statements come from.
+    def initialize(local_variables:)
+      @local_variables = local_variables
+    end
+
+    # @param node [Parser::AST::Node] the statement to render.
+    # @return [String] Unparser's render, informed of the tree's locals.
+    def unparse(node)
+      Unparser.unparse(node, static_local_variables: @local_variables)
+    end
+
+    # Renders +node+ no taller than its source when safely possible. Unparser normalizes some single-line
+    # constructs into multi-line form (e.g. modifier-if into if/end); when the render is taller than the
+    # statement's source, compress it back to one line — verified by re-parse so a statement that cannot be safely
+    # single-lined (e.g. containing a heredoc) falls back to its multi-line render.
+    def aligned_render(node)
+      render = unparse(node)
+      loc = node.loc
+      return render unless loc.respond_to?(:last_line) && loc.line
+
+      source_height = loc.last_line - loc.line + 1
+      return render if render.count("\n") < source_height
+
+      compress_to_single_line(render) || render
+    end
+
+    private
+
+    def compress_to_single_line(render)
+      candidate = render.split("\n").map(&:strip).join('; ')
+      # Both sides parsed without scope context, so lvar/send ambiguity cancels out; equality means the newline
+      # join preserved structure.
+      Unparser.parse(candidate) == Unparser.parse(render) ? candidate : nil
+    rescue Parser::SyntaxError
+      nil
+    end
+  end
+end

data/lib/ast_transform/testing/assertions.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'ast_transform/transformer'
+require 'ast_transform/instruction_sequence'
+
+module ASTTransform
+  module Testing
+    # Assertions for transform authors' own test suites — the enforcement arm of the authoring contract ("textual
+    # order is source order"). Minitest-flavored. Never loaded in production; require it from test code:
+    #
+    #   require "ast_transform/testing/assertions"
+    #
+    #   class MyTransformationTest < Minitest::Test
+    #     include ASTTransform::Testing::Assertions
+    #   end
+    module Assertions
+      # Transforms +source+ through the real pipeline (transform + line-aligned emission), re-parses both sides,
+      # matches surviving statements by location, and asserts each one's emitted line equals its source line.
+      # Statements the transform deletes (e.g. description strings) are exempt; statements the transform rewrites in
+      # place keep their anchor and are checked.
+      #
+      # @param source [String] fixture source
+      # @param transformations [Array<ASTTransform::AbstractTransformation>]
+      # @param path [String] pseudo-path used for parsing and messages
+      # @return [void]
+      def assert_line_aligned(source, *transformations, path: 'fixture.rb')
+        transformer = Transformer.new(*transformations)
+        emitted = transformer.transform_file_source(source, path, path)
+
+        source_lines_by_statement = statement_lines(transformer.build_ast(source, file_path: path))
+        emitted_lines_by_statement = statement_lines(transformer.build_ast(emitted, file_path: path))
+
+        misaligned = source_lines_by_statement.filter_map do |render, source_line|
+          emitted_line = emitted_lines_by_statement[render]
+          next if emitted_line.nil? || emitted_line == source_line
+
+          format('  MISALIGNED %s: source line %d, emitted line %d', render, source_line, emitted_line)
+        end
+
+        assert misaligned.empty?, <<~MESSAGE
+          expected every surviving statement at its source line in #{path}:
+          #{misaligned.join("\n")}
+
+          emitted:
+          #{numbered_listing(emitted)}
+        MESSAGE
+      end
+
+      # Runtime complement of assert_line_aligned: compiles +source+ through the full pipeline under +path+, executes
+      # it, and asserts the raw first backtrace frame — no filtering of any kind — is "<path>:<raise_at>".
+      #
+      # @param source [String] fixture that raises when executed
+      # @param path [String] pseudo source path to compile under
+      # @param raise_at [Integer] expected source line of the raise
+      # @return [void]
+      def assert_backtrace_lines(source, path:, raise_at:)
+        iseq = InstructionSequence.source_to_transformed_iseq(source, path)
+
+        error = assert_raises(StandardError, "fixture at #{path} should raise when executed") do
+          iseq.eval
+        end
+
+        location = error.backtrace_locations.first
+        assert_equal "#{location.path}:#{raise_at}", "#{location.path}:#{location.lineno}",
+          "raw backtrace should cite source line #{raise_at} of #{path}"
+      end
+
+      private
+
+      # Flat statement renders and their first line, keyed by unparsed text so source and emitted sides can be matched
+      # without location identity. Duplicate renders keep their first occurrence — good enough for fixtures, which
+      # authors control.
+      def statement_lines(ast, lines = {})
+        return lines unless ast.is_a?(::Parser::AST::Node)
+
+        if statement_sequence?(ast)
+          ast.children.each do |statement|
+            next unless statement.is_a?(::Parser::AST::Node) && statement.loc&.expression
+
+            lines[Unparser.unparse(statement)] ||= statement.loc.line
+          end
+        end
+
+        ast.children.each { |child| statement_lines(child, lines) }
+        lines
+      end
+
+      def statement_sequence?(node)
+        [:begin, :kwbegin].include?(node.type)
+      end
+
+      def numbered_listing(source)
+        source.lines.map.with_index(1) { |line, number| format('%3d| %s', number, line) }.join
+      end
+    end
+  end
+end