ast_transform 2.1.4 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '02391c6a71f241da83617ab3dae2ff61a66c7a9ad3f9d154c6f6f3aee29e86ad'
-  data.tar.gz: 9b25a4ae5581efc378793af4b4d3d4fd697cc88104567610caf4dea77c2d4d64
+  metadata.gz: a74867dd7f6d788c78d286901e1e4c6a362e0a341300fb9bb22ccb92503a0223
+  data.tar.gz: c2968b8000a875e169f89d85deaa38868ad49dcc8d193db6a78c88ea4eafb986
 SHA512:
-  metadata.gz: 0e0c312499e1abdd8eea7f2c704cf3aaca4a06ed1b7c62c048bb6f4b350b85a89fc9170c8dc0d0cfd84d5b1e2c9822608a4767600350c097b1da1f4c98f5d759
-  data.tar.gz: d02faba1167586d4bb7aceb138b3452e3cb9ab7c2f294ae02803fb09a565d5ea884ec44568ec60efa1ab3b6600cc17fe911559c02afb6d8e5350bf37ce83ed04
+  metadata.gz: 9f4e007503a09479a7df3f595097bf384eb0196fb192cd012855c63417582e34a32cfd318ae765f1a8122de408bbfd337c8e3adfe889d2fd1bc36b3a20c96599
+  data.tar.gz: 900412939feb57ee329d2c3adca9b9712c1da8243038268104db916f9270ea09427d0d96cbf5aded11f86d919d4b45e6629be20372eb4dfc1d0531f05757b1e5

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,28 @@ 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.1.0] - 2026-07-29
+### Added
+- Analysis passes: `ASTTransform::AbstractAnalysis`, the read-only counterpart of `AbstractTransformation`. Both leaves share the extracted traversal core `ASTTransform::AbstractProcessor` (sealed `process`, `process_node` hook, thunk descent, `TransformationHelper`) and differ only in what `run` returns — the rebuilt tree for transformations, the analysis instance (result readers) for analyses.
+- Public parse seam: `ASTTransform::SourceParser` (`#parse(source, file_path:)` / `#parse_file(path)`) extracts the framework's Prism-backed parsing from `Transformer` so analysis-only consumers that never emit can instantiate it directly. `Transformer#build_ast` / `#build_ast_from_file` delegate to it (unchanged public behavior).
+- Pass-taxonomy documentation on `AbstractTransformation`, `Transformation`, and the README: structural (`on_*` handlers, pattern matched anywhere), positional (node builders with the bare `run(node) → node` duck type, caller owns traversal), and sibling-annotation (marker statement + next sibling, matched in `process_node` where the child list is visible — `transform!` itself).
+
+## [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.4)
-      parser (>= 3.0)
+    ast_transform (3.1.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:
@@ -128,6 +130,16 @@ class MyTransformation < ASTTransformation::AbstractTransformation
 end
 ```
 
+#### Choosing a pass shape
+
+Passes come in three shapes, distinguished by how the rewrite site is found:
+
+* **Structural** — the pattern alone identifies the site. Subclass `AbstractTransformation` and write `on_*` handlers; the pass rewrites the pattern wherever it occurs in the tree.
+* **Positional (node builders)** — the *caller* owns traversal and has already located the site. Implement a plain `run(node) → node` object (include `TransformationHelper` for the `s(...)` vocabulary); the builder maps a single node to its replacement subtree and never walks. Anything with that duck type composes with `Transformer` and other passes.
+* **Sibling-annotation** — the pattern is a marker statement plus its NEXT sibling. Match in `process_node`, where a node's child list is visible: an `on_*` handler sees one node, never its siblings, and cannot delete itself from its parent. `ASTTransform::Transformation` (the `transform!` detector) is the canonical example.
+
+For read-only passes that harvest information instead of rewriting, see [Analysis passes](#analysis-passes).
+
 #### Transformation discoverability
 
 ASTTransform automatically loads your transformations at compile time. As such, we expect your files to be located at a known path.
@@ -160,6 +172,96 @@ 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.
 
+### Analysis passes
+
+Not every pass rewrites. An analysis walks the tree and harvests information — `Parser::AST::Processor` has no read-only mode (every walk functionally rebuilds the tree), so an analysis is simply a walk whose rebuilt tree is discarded. Derive from `ASTTransform::AbstractAnalysis`: it shares the traversal engine with `AbstractTransformation` (including thunk descent and the `s(...)` matching vocabulary) and differs only in what `run` returns — the analysis instance, so callers chain result readers off the run.
+
+```ruby
+require 'ast_transform/abstract_analysis'
+
+class TypeAliasRanges < ASTTransform::AbstractAnalysis
+  attr_reader :ranges
+
+  def initialize
+    @ranges = []
+    super
+  end
+
+  def on_block(node)
+    send_node = node.children.first
+    @ranges << (node.loc.expression.first_line..node.loc.expression.last_line) if type_alias?(send_node)
+    super
+  end
+
+  private
+
+  def type_alias?(send_node)
+    send_node == s(:send, s(:const, nil, :T), :type_alias)
+  end
+end
+```
+
+Harvest state in `on_*` handlers and always call `super` so traversal continues. Node equality ignores source locations, so `s(...)` patterns match structurally.
+
+Analysis-only consumers don't need a `Transformer`; instantiate the parsing seam directly (`Transformer` uses the same class internally) and keep the instance for as many parses as you need:
+
+```ruby
+parser = ASTTransform::SourceParser.new
+
+parser.parse(source)          # => Parser::AST::Node
+parser.parse_file(file_path)  # => Parser::AST::Node
+
+TypeAliasRanges.new.run(parser.parse(source)).ranges
+```
+
+### 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 +285,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 +295,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 +303,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_analysis.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "ast_transform/abstract_processor"
+
+module ASTTransform
+  # Base class for read-only analysis passes: subclass, harvest state in +on_*+ handlers (always call +super+ so
+  # traversal continues), and expose results through readers. The walk still functionally rebuilds the tree —
+  # Parser::AST::Processor has no read-only mode — but +run+ discards the rebuilt tree, so handlers never need to
+  # care what they return.
+  #
+  #   class SendCounter < ASTTransform::AbstractAnalysis
+  #     attr_reader :count
+  #
+  #     def initialize
+  #       @count = 0
+  #       super
+  #     end
+  #
+  #     def on_send(node)
+  #       @count += 1
+  #       super
+  #     end
+  #   end
+  #
+  #   SendCounter.new.run(SourceParser.new.parse(source)).count
+  class AbstractAnalysis < AbstractProcessor
+    # Runs this analysis on +node+, discarding the rebuilt tree.
+    # Note: If you want to add one-time setup or result finalization, override this, then call super.
+    #
+    # @param node [Parser::AST::Node] The node to be analyzed.
+    #
+    # @return [ASTTransform::AbstractAnalysis] self, so callers can chain result readers off the run.
+    def run(node)
+      process(node)
+      self
+    end
+  end
+end

data/lib/ast_transform/abstract_processor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "ast_transform/transformation_helper"
+
+module ASTTransform
+  # Shared traversal core for tree passes. Parser::AST::Processor is a rewriting walker — every visit functionally
+  # rebuilds the tree — so transformation and analysis share one engine and differ only in what they keep:
+  # AbstractTransformation's +run+ returns the rebuilt tree, AbstractAnalysis's +run+ discards it and returns the
+  # harvested results. Subclass one of those leaves rather than this class.
+  class AbstractProcessor < Parser::AST::Processor
+    include TransformationHelper
+
+    # Used internally by Parser::AST::Processor to process each node. DO NOT OVERRIDE.
+    def process(node)
+      return node unless node.is_a?(Parser::AST::Node)
+
+      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 pass. 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+.
+    # Note: If you want to do processing on each node, override this.
+    #
+    # @param node [Parser::AST::Node] The node being visited.
+    #
+    # @return [Parser::AST::Node] The rebuilt node.
+    def process_node(node)
+      method(:process).super_method.call(node)
+    end
+  end
+end

data/lib/ast_transform/abstract_transformation.rb

@@ -1,11 +1,24 @@
 # frozen_string_literal: true
-require 'ast_transform/transformation_helper'
 
-module ASTTransform
-  class AbstractTransformation < Parser::AST::Processor
-    include TransformationHelper
+require "ast_transform/abstract_processor"
 
-    # Runs this transformation on +node+.
+module ASTTransform
+  # Base class for structural transformations: subclass and write +on_*+ handlers to rewrite a pattern wherever it
+  # occurs in the tree. This is one of three authoring shapes — pick by how the rewrite site is found:
+  #
+  # - Structural (this class): the pattern alone identifies the site, so +on_*+ handlers rewrite it anywhere in
+  #   the tree.
+  # - Positional (node builders): a plain object with +run(node) → node+, including only TransformationHelper. The
+  #   caller owns traversal and applies the builder at a site it already located; the builder never walks. Anything
+  #   with that duck type composes with Transformer and other passes — deriving from this class is just one way to
+  #   implement it.
+  # - Sibling-annotation: the pattern is a marker statement plus its NEXT sibling, matched in +process_node+ where
+  #   the child list is visible — an +on_*+ handler sees one node, never its siblings, and cannot delete itself
+  #   from its parent. See ASTTransform::Transformation (the +transform!+ detector) for the canonical example.
+  #
+  # For read-only passes that harvest information instead of rewriting, see ASTTransform::AbstractAnalysis.
+  class AbstractTransformation < AbstractProcessor
+    # Runs this transformation on +node+ and returns the rebuilt tree.
     # Note: If you want to add one-time checks to the transformation, override this, then call super.
     #
     # @param node [Parser::AST::Node] The node to be transformed.
@@ -14,24 +27,5 @@ module ASTTransform
     def run(node)
       process(node)
     end
-
-    # Used internally by Parser::AST::Processor to process each node. DO NOT OVERRIDE.
-    def process(node)
-      return node unless node.is_a?(Parser::AST::Node)
-
-      process_node(node)
-    end
-
-    private
-
-    # Processes the given +node+.
-    # Note: If you want to do processing on each node, override this.
-    #
-    # @param node [Parser::AST::Node] The node to be transformed.
-    #
-    # @return [Parser::AST::Node] The transformed node.
-    def process_node(node)
-      method(:process).super_method.call(node)
-    end
   end
 end

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
@@ -15,7 +16,7 @@ module ASTTransform
         # 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.include?('transform!'.b)
+        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