ast_transform 2.1.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3322dbf3c31a96df5ddea9892b60c40b785842500c13f178d1a9b11b5842bf12
-  data.tar.gz: aef4ed8d812275368ec5f22c61d9b3d049ecc42490c406d08e8afd4e34e589e7
+  metadata.gz: d42a8d0999b373707aeb231d0c8bcf50ef7011ef8fd2bc2e9de9e7fda131550b
+  data.tar.gz: e7dccb5d7359e7fd974b5497ffbdf433458141ea278e25e937b3dda1c574dc2b
 SHA512:
-  metadata.gz: bfd3828a33d2668a854ed4d5b1c299615ca47e92232ccf6705b008437cdb43e6497b9ef517e2664f5cd68b9197f9cc78ef2bd50090152f7889490a18e28cf72a
-  data.tar.gz: 6f9647eaad1208d3cacb9ba038f8e63ff213d1ae7030bb96ec0a28386125096526f64bffa93100795427d67c2671b2638711c9ca891222beac01b0c046a07afc
+  metadata.gz: ad852344a9213e684c9e8f05e98d7d0292d654ee2ca2a4af14aaa230428ecdb165579bf914fc0e751259e22f0712553e4a8c7b4ae65d776a946baa055a67cd50
+  data.tar.gz: 5e20310267e2f0b233eb790cc10808436dfdbf5f6c7d8700935982ffefdeae1660a8fac0df1f4e933ed3704c96079dbea2526109ec3d8eb4e60f5054313793ea

data/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @JPDuchesne

data/.github/workflows/ci.yml

@@ -7,12 +7,22 @@ on:
     branches: [main, master]
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+      - run: bundle exec rubocop
+
   test:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.2', '3.3', '4.0']
+        ruby: ['3.3', '3.4', '4.0']
     steps:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1

data/.gitignore

@@ -50,4 +50,7 @@ build-iPhoneSimulator/
 .rvmrc
 
 # RubyMine
-/.idea
+/.idea
+
+# Generated per-machine by `dev up` (d3mlabs dev tool); never committed
+/.shadowenv.d/

data/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_gem:
+  rubocop-shopify: rubocop.yml
+
+AllCops:
+  SuggestExtensions: false

data/.ruby-version

@@ -0,0 +1 @@
+4.0.6

data/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-07-24
+### Added
+- Line-aligned emission: transformed code is emitted with every loc-carrying statement on its original source line, making backtraces, breakpoints, and debugger display correct by construction (`LineAlignedEmitter`).
+- Authoring toolkit in `TransformationHelper`: `s_at` (loc-anchored node construction), `thunk` (a single invariant-checked `Thunk` node spliced at the execution point; the lowering derives the hidden proc's textual placement from the body's source locations), and `run_after` (sequence-level execution reordering that preserves textual/source order). Thunks lower to a non-lambda proc, so `return` still returns from the enclosing method, and locals assigned by thunked statements are pre-declared to stay method-scope. Reusing one thunk node executes its body from several points.
+- `ASTTransform::Node.register`: type-routed construction of custom IR node classes through `s`, with an emitter postcondition (`LineAlignedEmitter::UnloweredNodeTypeError`) rejecting custom types that were not lowered before emission.
+- `ast_transform/testing/assertions` (test-only): `assert_line_aligned` and `assert_backtrace_lines` for transform authors' suites.
+- Error types, each owned by its producer: `TransformationHelper::MissingLocationError`, `ThunkLowering::PlacementError`, `LineAlignedEmitter::UnloweredNodeTypeError`. Thunk construction invariants raise plain `ArgumentError`.
+
+### Removed
+- **Breaking:** `ASTTransform::SourceMap` and source-map registration. Line-aligned emission makes raw VM line numbers the source line numbers, so there is nothing left to map at display time.
+
+### Changed
+- **Breaking:** `Transformer#transform` and `#transform_file_source` emit line-aligned output (source-anchored layout, always newline-terminated) instead of Unparser's re-normalized formatting.
+- **Breaking:** dropped Ruby 3.2 support (EOL since March 2026); `required_ruby_version` is now `>= 3.3`.
+- Dependency floors now reflect reality: `unparser >= 0.8` (the emitter uses `static_local_variables:`, a 0.7 interface, and 0.8's prism-based round-trip verification is required for Ruby >= 3.4 syntax) and `parser >= 3.3` (unparser's own floor; the declared `>= 3.0` could never resolve lower).
+
 ## [0.1.4] 2019-06-20
 ### Fixed
 - Source mapping for transformations wrapping source nodes into virtual nodes now work.

data/Gemfile

@@ -1,6 +1,17 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in ast_transform.gemspec
 gemspec
+
+# Development dependencies
+gem "bundler", ">= 2.1"
+gem "minitest", "~> 5.14"
+gem "minitest-reporters", "~> 1.4"
+gem "pry", ">= 0.14"
+gem "rake", "~> 13.0"
+gem "rubocop-shopify", "~> 3.0", require: false
+gem "simplecov", "~> 0.22"

data/Gemfile.lock

@@ -1,29 +1,33 @@
 PATH
   remote: .
   specs:
-    ast_transform (2.1.2)
-      parser (>= 3.0)
+    ast_transform (3.0.0)
+      parser (>= 3.3)
       prism (>= 1.5)
-      unparser (>= 0.6)
+      unparser (>= 0.8)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ansi (1.5.0)
+    ansi (1.6.0)
     ast (2.4.3)
     builder (3.3.0)
     coderay (1.1.3)
-    diff-lcs (1.6.2)
+    diff-lcs (2.0.0)
     docile (1.4.1)
     io-console (0.8.2)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
     method_source (1.1.0)
     minitest (5.27.0)
-    minitest-reporters (1.7.1)
+    minitest-reporters (1.8.0)
       ansi
       builder
-      minitest (>= 5.0)
+      minitest (>= 5.0, < 7)
       ruby-progressbar
-    parser (3.3.10.2)
+    parallel (2.1.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
@@ -32,9 +36,28 @@ GEM
       method_source (~> 1.0)
       reline (>= 0.6.0)
     racc (1.8.1)
-    rake (13.3.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-shopify (3.0.1)
+      lint_roller
+      rubocop (~> 1.72, >= 1.72.1)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
@@ -42,8 +65,11 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    unparser (0.8.1)
-      diff-lcs (~> 1.6)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    unparser (0.9.0)
+      diff-lcs (>= 1.6, < 3)
       parser (>= 3.3.0)
       prism (>= 1.5.1)
 
@@ -58,6 +84,7 @@ DEPENDENCIES
   minitest-reporters (~> 1.4)
   pry (>= 0.14)
   rake (~> 13.0)
+  rubocop-shopify (~> 3.0)
   simplecov (~> 0.22)
 
 BUNDLED WITH

data/README.md

@@ -5,6 +5,8 @@
 
 ASTTransform is an Abstract Syntax Tree (AST) transformation framework. It hooks into the compilation process and allows to perform AST transformations using an annotation: `transform!`.
 
+Transformed code is emitted **line-aligned**: every statement carrying a source location is placed on its original source line. Backtraces, failure messages, `break file:line` breakpoints, and debugger display are therefore correct by construction — no source maps, no backtrace filtering, no debugger integration required.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -160,6 +162,54 @@ In the above, `node#updated` allows updating the node, either its type or its ch
 
 The [ast gem](https://github.com/whitequark/ast) uses a pattern in which a Transformation may implement a method matching a node type, i.e. `on_class`, `on_send`, `on_lvar`, etc... This is very useful when transformations should process all nodes of this type.
 
+### Line-aligned emission and the authoring contract
+
+ASTTransform owns text and lines; transform authors own semantics and execution order. The contract:
+
+* A node **with** a source location is emitted at that location's line (the emitter pads with blank lines to reach it, and packs with `;` when a line is already occupied).
+* A node **without** a source location is synthetic: it packs onto the current line and inherits its neighbors' line number.
+* Textual order is source order. If your transform needs code to *execute* in a different order than it *appears*, use a thunk (below) instead of moving nodes.
+
+`ASTTransform::TransformationHelper` (included by `AbstractTransformation`) provides the authoring toolkit:
+
+* `s(type, *children)` — builds a loc-less (synthetic) node. Registered custom types (see below) construct their registered class.
+* `s_at(anchor, type, *children)` — builds a node anchored at `anchor`'s source location, so it is emitted at `anchor`'s line. Raises `TransformationHelper::MissingLocationError` if the anchor has no location.
+* `thunk(*statements)` — wraps statements in a single `Thunk` node: splice it wherever the statements must *run*, in statement position or composed inside an expression (e.g. an `assert_raises` block body). The wrapped statements keep their own locations, and the lowering derives the hidden proc's textual placement from them — the body still emits on its source lines even though execution waits. Reuse the same node to execute one body from several points. Thunk construction is invariant-checked (`ArgumentError` on a missing id or empty body); a body whose source lines fall after its execution point fails lowering with `ThunkLowering::PlacementError` (a thunk can only delay execution, never text).
+* `run_after(statements, run:, after:)` — the paved road over `thunk`: returns a reordered copy of `statements` where the contiguous `run` executes after `after`, while remaining at its source position textually. Elements are matched by object identity.
+
+Thunked statements keep their original meaning as far as Ruby's closure semantics allow:
+
+* `return` still returns from the enclosing method — the hidden closure is a non-lambda proc, and the proc and its call always share one method activation (placements never cross a `def` boundary).
+* Locals assigned by the thunked statements stay method-scope: the lowering pre-declares each one (`result = result`) before the proc, so code after the execution point can read them. Before the thunk runs they are `nil` — exactly what an unexecuted assignment yields.
+* Jump keywords whose owner lies *outside* the thunked statements keep Ruby's native behavior: `break`/`retry` raise `LocalJumpError` at the jump's own source line, while `next`/`redo` silently end or restart the thunk body. ASTTransform does not validate this — what a transform surface allows users to thunk is the transform author's call.
+
+#### Gotcha: location-only rewrites are silently dropped
+
+`Parser::AST::Node#updated` returns `self` when the new children compare `==` to the old ones — and `AST::Node#==` ignores source locations. A `Processor` pass that replaces a node with an equal-valued one (e.g. the same call rebuilt loc-less, hoping to change its emitted line) is a no-op: every `node.updated(nil, process_all(node))` up the tree discards the replacement. Location is part of a node's *emission*, not its *value* — to change where a node emits, change what it is (`s_at` an anchored rebuild with different children), or restructure the parent explicitly rather than relying on `updated`.
+
+#### Custom node types (intermediate representation)
+
+Transformations that parse a DSL can build their own IR by registering node classes:
+
+```ruby
+class InteractionNode < ASTTransform::Node
+  register :my_interaction
+
+  def cardinality = children[0]
+end
+
+s(:my_interaction, ...) # => InteractionNode, with domain accessors
+```
+
+Custom node types are IR **between stages that understand them** — the stage that owns a type must lower it to plain Ruby nodes before emission. The emitter enforces this: any registered or `ast_`-prefixed type reaching emission raises `LineAlignedEmitter::UnloweredNodeTypeError`.
+
+#### Testing your transformation
+
+`require 'ast_transform/testing/assertions'` (test-only) provides `ASTTransform::Testing::Assertions`, a Minitest-flavored module to include in your test class:
+
+* `assert_line_aligned(source, *transformations)` — transforms `source` through the real pipeline and asserts every surviving statement is emitted at its source line.
+* `assert_backtrace_lines(source, path:, raise_at:)` — compiles and executes `source`, asserting the raw first backtrace frame cites `path:raise_at` with no filtering.
+
 ### Parameterizable transformations
 
 If you want your transformation to be customizable, accept the parameters in the constructor. The annotation can the be changed accordingly:
@@ -183,6 +233,8 @@ end
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+If you use the [d3mlabs dev tool](https://github.com/d3mlabs/dev), `dev up` provisions the pinned Ruby (see `.ruby-version`) with a per-project shadowenv, and `dev test` runs the suite — plain Bundler as above works just as well.
+
 To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Releasing a New Version
@@ -191,7 +243,7 @@ There are two ways to create a release. Both require that `version.rb` has alrea
 
 ### Via GitHub UI
 
-1. Update `VERSION` in `lib/ast_transform/version.rb`, commit, open a PR, and merge to main
+1. Update `VERSION` in `lib/ast_transform/version.rb` and run `bundle install` to regenerate `Gemfile.lock`, commit, open a PR, and merge to main
 2. Go to the repo on GitHub → **Releases** → **Draft a new release**
 3. Enter a new tag (e.g. `v2.0.0`), select `main` as the target branch
 4. Add a title and release notes (GitHub can auto-generate these from merged PRs)
@@ -199,7 +251,7 @@ There are two ways to create a release. Both require that `version.rb` has alrea
 
 ### Via CLI
 
-1. Update `VERSION` in `lib/ast_transform/version.rb`, commit, open a PR, and merge to main
+1. Update `VERSION` in `lib/ast_transform/version.rb` and run `bundle install` to regenerate `Gemfile.lock`, commit, open a PR, and merge to main
 2. Tag and push:
    ```
    git checkout main && git pull

data/Rakefile

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+
+require "bundler/gem_tasks"
+require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
   # Ensure we load test_loader first for ASTTransform.install
-  filepath = File.expand_path('test/test_loader.rb', __dir__)
+  filepath = File.expand_path("test/test_loader.rb", __dir__)
   t.ruby_opts << "-r #{filepath}"
   t.warning = false
 
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task :default => :test
+task default: :test

data/ast_transform.gemspec

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
@@ -9,28 +10,26 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Jean-Philippe Duchesne"]
   spec.email         = ["jpduchesne89@gmail.com"]
 
-  spec.summary       = 'An AST transformation framework.'
+  spec.summary       = "An AST transformation framework."
   spec.description   = spec.summary
   spec.homepage      = "https://github.com/rspockframework/ast-transform"
   spec.license       = "MIT"
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+  spec.files         = %x(git ls-files -z).split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-  spec.required_ruby_version = '>= 3.2'
+  spec.required_ruby_version = '>= 3.3'
 
-  # Development dependencies
-  spec.add_development_dependency "bundler", ">= 2.1"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "minitest", "~> 5.14"
-  spec.add_development_dependency "minitest-reporters", "~> 1.4"
-  spec.add_development_dependency "pry", ">= 0.14"
-  spec.add_development_dependency "simplecov", "~> 0.22"
+  # Development dependencies live in the Gemfile (Gemspec/DevelopmentDependencies).
 
   # Runtime dependencies
-  spec.add_runtime_dependency "parser", ">= 3.0"
+  # parser provides the runtime AST vocabulary (Parser::AST::Node/Processor,
+  # Source::Buffer/Map); parsing itself goes through prism's translation layer.
+  spec.add_runtime_dependency "parser", ">= 3.3"
   spec.add_runtime_dependency "prism", ">= 1.5"
-  spec.add_runtime_dependency "unparser", ">= 0.6"
+  # unparser >= 0.8: static_local_variables: (0.7 interface) + the prism-based
+  # round-trip verification parser required for Ruby >= 3.4 syntax.
+  spec.add_runtime_dependency "unparser", ">= 0.8"
 end

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "bundler/setup"
 require "ast_transform"

data/dependencies.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Toolchain-only manifest for d3mlabs' dev tool: it provisions this exact
+# Ruby (rbenv + shadowenv) for `dev` commands. Gems stay bundler-managed
+# through the hand-written gemspec/Gemfile; contributors without dev can
+# ignore this file and use .ruby-version.
+require "dev/deps"
+
+Dev::Deps.define do
+  ruby "4.0.6"
+end

data/dev.yml

@@ -0,0 +1,11 @@
+name: ast_transform
+commands:
+  up:
+    desc: Install gems
+    run: bundle install
+  test:
+    desc: Run this repo's tests
+    run: bundle exec rake test
+  style:
+    desc: Run RuboCop
+    run: bundle exec rubocop

data/lib/ast_transform/abstract_transformation.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-require 'ast_transform/transformation_helper'
+
+require "ast_transform/transformation_helper"
 
 module ASTTransform
   class AbstractTransformation < Parser::AST::Processor
@@ -22,6 +23,14 @@ module ASTTransform
       process_node(node)
     end
 
+    # Thunks are framework-owned IR: descend into the body so passes that don't know about thunks still process the
+    # wrapped statements. Without this, Processor's handler_missing default would pass the node through opaquely,
+    # hiding the body from every later transformation. The token (first child) is not a node and passes through
+    # untouched.
+    def on_ast_thunk(node)
+      node.updated(nil, [node.children[0], *process_all(node.children.drop(1))])
+    end
+
     private
 
     # Processes the given +node+.

data/lib/ast_transform/instruction_sequence/bootsnap_mixin.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'ast_transform/transformer'
-require 'ast_transform/instruction_sequence/mixin_utils'
-require 'pathname'
+require "ast_transform/transformer"
+require "ast_transform/instruction_sequence/mixin_utils"
+require "pathname"
 
 module ASTTransform
   module InstructionSequence
@@ -14,7 +14,7 @@ module ASTTransform
         iseq = ASTTransform::InstructionSequence.source_to_transformed_iseq(source, source_path)
         iseq.to_binary
       rescue SyntaxError
-        raise ::Bootsnap::CompileCache::Uncompilable, 'syntax error'
+        raise ::Bootsnap::CompileCache::Uncompilable, "syntax error"
       end
     end
   end

data/lib/ast_transform/instruction_sequence/mixin.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
-require 'pathname'
-require 'ast_transform/transformer'
-require 'ast_transform/transformation'
-require 'ast_transform/instruction_sequence/mixin_utils'
+
+require "pathname"
+require "ast_transform/transformer"
+require "ast_transform/transformation"
+require "ast_transform/instruction_sequence/mixin_utils"
 
 module ASTTransform
   module InstructionSequence
@@ -10,9 +11,12 @@ module ASTTransform
       def load_iseq(source_path)
         return ASTTransform::MixinUtils.try_super(self, :load_iseq, source_path) if source_path == __FILE__
 
-        source = File.read(source_path)
+        # Binary read avoids encoding errors during the fast-path check below.
+        # Downstream (Prism, RubyVM::InstructionSequence) handle encoding natively
+        # via magic comments, so we never need to set it ourselves.
+        source = File.binread(source_path)
 
-        return ASTTransform::MixinUtils.try_super(self, :load_iseq, source_path) unless source =~ /transform!/
+        return ASTTransform::MixinUtils.try_super(self, :load_iseq, source_path) unless source.include?("transform!".b)
 
         ASTTransform::InstructionSequence.source_to_transformed_iseq(source, source_path)
       end

data/lib/ast_transform/instruction_sequence/mixin_utils.rb

@@ -5,7 +5,7 @@ module ASTTransform
     class << self
       def try_super(target, method_sym, *args, &block)
         super_method = target.method(method_sym).super_method
-        super_method ? super_method.call(*args, &block) : nil
+        super_method&.call(*args, &block)
       end
     end
   end

data/lib/ast_transform/instruction_sequence.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module ASTTransform
   module InstructionSequence
     class << self
@@ -16,18 +17,18 @@ module ASTTransform
         rewritten_source = transformer.transform_file_source(source, source_path, rewritten_file_pathname.to_s)
         write(rewritten_source, rewritten_file_pathname)
 
-        RubyVM::InstructionSequence.compile(rewritten_source, rewritten_file_pathname.to_s, rewritten_file_pathname.to_s)
+        RubyVM::InstructionSequence.compile(rewritten_source, source_path, source_path)
       end
 
       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,16 +1,18 @@
 # 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.
+  # Extends the default Prism parser builder to distinguish 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.
+  # 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.
+  #
+  # 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

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