rspock 2.5.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6c10b52d342827b092af647c5bc144f4e381dff91167eedf93a0f99c9488ee2
-  data.tar.gz: 20ea274b4fa0e3a79eefb88f33c53ddf84adfc582fd37fe3e2ee9688a8137747
+  metadata.gz: 78c080ee35d24e8f92601d74cef95ea7bd3e98bee05a47c2ab0a85b327efdf6a
+  data.tar.gz: dd3636b68aca10d31b3813183622ecd3dbef278194c522692bd3f542dd39c08e
 SHA512:
-  metadata.gz: '019855311bf85f23d10fb75d3b1c0020b52fbf2ae7083205ca69a3f15b142ee7c2ba24e9be0506c690e65b42302b347ea7dc256c596edf1069ec8a0700aad666'
-  data.tar.gz: a559d70b0f3509d361234019935a2105c4a2b96ddac5ce0df7198edff346fe83a5c7a9c889d5152fbf0a856a60edd069017c3b24f88b144eda651ab35a57b47b
+  metadata.gz: 6a671720b23a938a90a6d7ad598aa445b457cb60c9e98c77d8c88be16f0dd0070a49e343d778a4832c6738dc839fa414653118af3dd0d76e766b378b9d46803b
+  data.tar.gz: 32426daeb51bde329ba4c501c589be13d95c17ecaea9471cc397a3912621fa0336c616d08cb969bd5fee737f08658380d168ac7362a0da7170448e258928e5e8

data/.github/CODEOWNERS

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

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     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/.ruby-version

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

data/CHANGELOG.md

@@ -5,7 +5,33 @@ 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.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [3.0.0] - 2026-07-24
+
+### Fixed
+
+- Locals assigned in a When block are now readable in Then and Cleanup when the test declares interactions. The thunked When body lowers to a non-lambda proc with method-scope pre-declarations, so `result = subject.call` in When no longer raises `NameError` in a Then expectation or in an ensure-run Cleanup — a long-standing bug of the hoisted-interaction era.
+
+### Changed
+
+- Adopted ast_transform 3.0 line-aligned emission: transformed code is emitted with every statement on its original source line, so backtraces, failure messages, breakpoints, and debugger display are source-true natively — with zero runtime filtering.
+- Interactions in Then blocks are emitted at their own source lines; the When body they must follow is wrapped in an ast_transform thunk instead of textually hoisting the interaction setups. A `return` inside the thunked body still returns from the test method (proc semantics).
+- Where-driven test names now embed the row line via internal block parameters (`__rspock_row_index__` / `__rspock_row_line__`); the appended `<index> line <line>` name suffix is unchanged.
+- RSpock node classes now register on `ASTTransform::Node` (the promoted registry) instead of RSpock's hand-rolled `Node::REGISTRY`/`NodeBuilder`.
+- **Breaking:** dropped Ruby 3.2 support (EOL since March 2026); `required_ruby_version` is now `>= 3.3`.
+
+### Removed
+
+- **Breaking:** the `_test_index_` and `_line_number_` test-scope variables. Isolate a Where row by running its generated test by name (the name embeds the row line; the failure output prints the exact rerun command) and break normally — see the README's "Isolating a Where Block row".
+- **Breaking:** the Rails generator (`rails g rspock:install`) and its backtrace-cleaner initializer template — there is no backtrace cleaning to configure anymore.
+- `RSpock::BacktraceFilter`, `RSpock::Minitest::BacktraceFilter`, and the Minitest plugin (`minitest/rspock_plugin`) — line-aligned emission makes raw VM line numbers the source line numbers, so the whole mapping apparatus is gone.
+- The rescue wrapper previously injected around transformed class bodies for backtrace mapping.
+- `MethodCallToLVarTransformation` (only existed to service `_test_index_`/`_line_number_`).
+- The direct `parser` and `unparser` runtime dependencies: rspock uses both only through ast_transform, which owns their version floors.
+
+### Added
+
+- Subprocess acceptance tests pinning line-aligned behavior end to end: Then assertion failures, failing Where rows, interaction setups, and Cleanup failures all cite their own source lines with zero filter machinery; When-assigned locals stay readable in Then and in ensure-run Cleanup when interactions thunk the When body.
+- The rspock agent skill (`skills/rspock/SKILL.md`) ships in the gem: the RSpock dialect's mechanics, pitfalls, and debugging triage for coding agents.
 
 ## [2.5.0] - 2026-02-28
 
@@ -152,7 +178,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release.
 
-[Unreleased]: https://github.com/rspockframework/rspock/compare/v2.5.0...HEAD
+[Unreleased]: https://github.com/rspockframework/rspock/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/rspockframework/rspock/compare/v2.5.0...v3.0.0
 [2.5.0]: https://github.com/rspockframework/rspock/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/rspockframework/rspock/compare/v2.3.1...v2.4.0
 [2.3.1]: https://github.com/rspockframework/rspock/compare/v2.3.0...v2.3.1

data/Gemfile.lock

@@ -1,22 +1,20 @@
 PATH
   remote: .
   specs:
-    rspock (2.5.0)
-      ast_transform (~> 2.0)
+    rspock (3.0.0)
+      ast_transform (~> 3.0)
       minitest (~> 5.0)
       mocha (>= 1.0)
-      parser (>= 3.0)
-      unparser (>= 0.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ansi (1.5.0)
+    ansi (1.6.0)
     ast (2.4.3)
-    ast_transform (2.1.4)
-      parser (>= 3.0)
+    ast_transform (3.0.0)
+      parser (>= 3.3)
       prism (>= 1.5)
-      unparser (>= 0.6)
+      unparser (>= 0.8)
     builder (3.3.0)
     byebug (13.0.0)
       reline (>= 0.6.0)
@@ -26,14 +24,14 @@ GEM
     io-console (0.8.2)
     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
-    mocha (3.0.2)
+    mocha (3.1.0)
       ruby2_keywords (>= 0.0.5)
-    parser (3.3.10.2)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
@@ -45,7 +43,7 @@ GEM
       byebug (~> 13.0)
       pry (>= 0.13, < 0.17)
     racc (1.8.1)
-    rake (13.3.1)
+    rake (13.4.2)
     reline (0.6.3)
       io-console (~> 0.5)
     ruby-progressbar (1.13.0)
@@ -56,7 +54,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    unparser (0.8.2)
+    unparser (0.9.0)
       diff-lcs (>= 1.6, < 3)
       parser (>= 3.3.0)
       prism (>= 1.5.1)

data/README.md

@@ -5,7 +5,7 @@
 
 RSpock is a testing and specification framework built on top of Minitest. It intends to give back productivity to its users with its incredibly simple yet highly expressive specification language.
 
-Note: RSpock is heavily inspired by Spock for the Groovy programming language.
+Note: RSpock is heavily inspired by [Spock](https://github.com/spockframework/spock) for the Groovy programming language.
 
 ## Goals
 
@@ -57,14 +57,6 @@ rakefile = "#{spec.gem_dir}/lib/Rakefile"
 load rakefile
 ```
 
-### Rails
-
-If you are using Rails, it is necessary to add a filter to *Rails.backtrace_cleaner* for [source mapping](#backtraces) to work, so that you get proper line numbers in Minitest backtraces. For your convenience, we've built a Rails Generator just for that:
-
-    $ rails g rspock:install
-
-Note: If you are not using Rails, you don't have anything to do, as RSpock includes a Minitest plugin that will set its own backtrace filter.
-
 ## Usage
 
 Getting started using RSpock is extremely easy!
@@ -297,6 +289,8 @@ This effectively creates one version of the Feature Method for each data row. No
 
 You might have noticed above that the test name contains string interpolations, that's one of the features of RSpock! You can interpolate test names and use Where block header variables to parameterize the test name using the test data.
 
+RSpock also appends each data row's index and source line number to the generated test name (e.g. `... 1 line 15`). This keeps names unique for identical data rows and gives the `-n` selector a stable target for isolating a row (see [Isolating a Where Block row](#isolating-a-where-block-row)).
+
 ##### Truth Table
 
 Formatting Where Blocks as a truth table is the recommended way to organize your Where Blocks in RSpock. It makes test cases more maintainable since it creates an order between the different test cases and makes it easier to spot missing or duplicated test cases. It also makes it easier to add a column:
@@ -537,49 +531,68 @@ end
 
 **Note**: Inline blocks (`do...end` or `{ }`) are not supported in interactions and will raise an `InteractionError`. Use a named proc or lambda variable with `&` instead, since block forwarding verification requires a reference to compare against.
 
-## Debugging
+#### Why Interactions Don't Support Block Yielding
+
+In Groovy Spock, you can make a mocked method yield its block via closure-based interaction responses. RSpock intentionally omits this. The `>>` operator stubs a return value only — it does not invoke the block argument passed to the mocked method.
 
-### Pry
+This is a deliberate design choice. If your test requires a mock to yield a block, it typically indicates one of two design smells:
 
-Let's be honest, at some point you will need to debug your tests. Because RSpock requires transforming the AST, the executed code is slightly different from the source code that you wrote. Although we have plans to add Source Mapping support in Pry so that you can see the exact source code you wrote, this is not currently available. This means that code shown in the Pry console will be slightly different. We think the value of using RSpock greatly outweighs this current limitation. We encourage you to try debugging a test to see what the transformed code looks like, or look through `tmp/rspock` for the transformed files.
+1. **The unit under test is doing too much.** A method that passes a block to a collaborator and then depends on that block's side effects to function correctly has too much coupling between the block body and the surrounding logic. Split the block's work into a separate, independently testable step.
 
-### Backtraces
+2. **The interaction boundary is in the wrong place.** If the block reads from IO, mutates state, or produces a return value that the caller depends on, the mock boundary cuts through the middle of a single responsibility. Restructure so the mock boundary sits between responsibilities, not within one.
 
-RSpock supports Source Mapping so that backtraces for the executed code point to the correct line numbers in your source code, and so that the correct files are referenced. This is achieved through wrapping the executed code in rescue blocks, processing the backtraces (source mapping) and re-raising the error.
+**Example: the better pattern**
 
-### Tips and Tricks
+Suppose you have a method that wraps work in a block-based collaborator:
 
-#### _test_index_ and _line_number_
+```ruby
+# Tightly coupled — block body depends on IO and collaborator
+def handle_spin(label, io)
+  @ui.with_spinner(label) do
+    drain_lines(io)  # block reads from IO; impossible to mock without yielding
+  end
+end
+```
 
-The generated test name for each test case will contain the test index and the line number, corresponding to the Where Block data row for that case, which is available in the test scope as `_test_index_` and `_line_number_` respectively. This can be leveraged to conditionally break on certain test cases, so that you can have a more granular debugging session.
+Testing this requires the mock to yield the block, otherwise `drain_lines` never runs and the IO stream is left unread. The fix is to separate the two concerns:
 
 ```ruby
-test "Adding #{a} and #{b} results in #{c}" do
-  When "Adding two numbers"
-  actual = a + b
+# Decoupled — each step is independently testable
+def handle_spin(label, io)
+  success = drain_lines(io)
+  success ? @ui.ok(label) : @ui.fail(label)
+end
+```
 
-  Then "We get the expected result"
-  # Breaks on the first test case
-  binding.pry if _test_index_ == 0
-  # Breaks on the second test case
-  binding.pry if _line_number_ == 15
-  actual == c
+Now `drain_lines` can be tested in isolation with a real IO (e.g. `StringIO`), and the UI interaction is a simple mock expectation with no block involved:
 
-  Where
-  a | b | c
-  1 | 2 | 3
-  4 | 5 | 9 # Line 15
+```ruby
+test "reports ok after draining" do
+  When "handle_spin completes"
+  handle_spin("Fetching", io)
+
+  Then "ok is called"
+  1 * @ui.ok("Fetching")
 end
 ```
 
-A few notes:
+This produces tests that are simpler, more explicit, and less coupled to implementation details. The constraint is the feature.
 
-* Comparison with `_test_index_` and `_line_number_` is not transformed to assertions in Then and Expect Code Blocks
-* `_test_index_` is zero-based, meaning the index of the first test case is `0`
+## Debugging
+
+Debugging just works. The transformed code is emitted line-aligned — every statement occupies its original source line — so backtraces, failure messages, `break file:line` breakpoints, and debugger display (Pry, byebug, debug.rb) all point at the file you wrote, with no filtering or mapping layer in between. The transformed files under `tmp/ast_transform` are a pure debugging artifact: their line numbers match your source exactly.
+
+One documented oddity: interaction setups in a `Then` block execute *before* the `When` body (see [Execution Order](#execution-order)), so stepping through a test with interactions jumps from the interaction lines back up to the `When` line once.
 
-#### _line_number_
+### Isolating a Where Block row
 
-The Line number is extremely useful for figuring out exactly which test case failed in your Where Block, especially if you have many rows in your Where Block data table.
+Each `Where` data row generates a separate test whose name embeds the row's index and source line number (e.g. `... 1 line 15`), so isolating a row is standard Minitest:
+
+* **Newly failing row:** copy the rerun command printed with the failure (the test name embeds the row line), add a plain `binding.pry` (or `debugger`) in the test body, and run it. It fires exactly once, for that row, with the column values inspectable as locals.
+* **Chosen row by position:** run with `-n` and a regex on the row's line number from your editor gutter, e.g. `-n /line_15/`.
+* **Chosen row by meaning:** use a conditional break on the column locals themselves, e.g. `binding.pry if input == "not json"` — this survives row reordering.
+
+Note: a source-line *breakpoint* on a data row cannot isolate that row's run — the Where table is evaluated once, in class scope, when tests are defined. Name-selection is the row-isolation mechanism.
 
 ## More info
 
@@ -620,6 +633,8 @@ end
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec 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

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,8 @@
+name: rspock
+commands:
+  up:
+    desc: Install gems
+    run: bundle install
+  test:
+    desc: Run this repo's tests
+    run: bundle exec rake test

data/lib/rspock/ast/interaction_to_mocha_mock_transformation.rb

@@ -30,7 +30,9 @@ module RSpock
         result = chain_call(interaction.receiver, :expects, s(:sym, interaction.message))
         result = chain_call(result, :with, *interaction.args.children) if interaction.args
         result = build_cardinality(result, interaction.cardinality)
-        result = chain_call(result, OUTCOME_METHODS.fetch(interaction.outcome.type), *interaction.outcome.children) if interaction.outcome
+        if interaction.outcome
+          result = chain_call(result, OUTCOME_METHODS.fetch(interaction.outcome.type), *interaction.outcome.children)
+        end
 
         if interaction.block_pass
           build_block_capture_setup(result, interaction.receiver, interaction.message)

data/lib/rspock/ast/node.rb

@@ -1,22 +1,13 @@
 # frozen_string_literal: true
-require 'ast_transform/transformation_helper'
+require 'ast_transform/node'
 
 module RSpock
   module AST
-    class Node < ::Parser::AST::Node
-      REGISTRY = {}
-
-      def self.register(type)
-        REGISTRY[type] = self
-      end
-
-      def self.build(type, *children)
-        klass = REGISTRY[type] || self
-        klass.new(type, children)
-      end
-    end
-
-    class TestNode < Node
+    # RSpock's intermediate representation: custom node types registered on ASTTransform::Node, so
+    # +s(:rspock_*, ...)+ constructs these classes with their domain accessors. They exist only between the parser
+    # and TestMethodTransformation — the transformation lowers every one of them to plain Ruby nodes before
+    # emission.
+    class TestNode < ASTTransform::Node
       register :rspock_test
 
       def def_node   = children[0]
@@ -24,38 +15,38 @@ module RSpock
       def where_node = children[2]
     end
 
-    class BodyNode < Node
+    class BodyNode < ASTTransform::Node
       register :rspock_body
     end
 
-    class DefNode < Node
+    class DefNode < ASTTransform::Node
       register :rspock_def
 
       def method_call = children[0]
       def args        = children[1]
     end
 
-    class GivenNode < Node
+    class GivenNode < ASTTransform::Node
       register :rspock_given
     end
 
-    class WhenNode < Node
+    class WhenNode < ASTTransform::Node
       register :rspock_when
     end
 
-    class ThenNode < Node
+    class ThenNode < ASTTransform::Node
       register :rspock_then
     end
 
-    class ExpectNode < Node
+    class ExpectNode < ASTTransform::Node
       register :rspock_expect
     end
 
-    class CleanupNode < Node
+    class CleanupNode < ASTTransform::Node
       register :rspock_cleanup
     end
 
-    class WhereNode < Node
+    class WhereNode < ASTTransform::Node
       register :rspock_where
 
       def header
@@ -70,7 +61,7 @@ module RSpock
       end
     end
 
-    class OutcomeNode < Node
+    class OutcomeNode < ASTTransform::Node
     end
 
     class StubReturnsNode < OutcomeNode
@@ -81,7 +72,7 @@ module RSpock
       register :rspock_stub_raises
     end
 
-    class RaisesNode < Node
+    class RaisesNode < ASTTransform::Node
       register :rspock_raises
 
       def exception_class = children[0]
@@ -89,7 +80,7 @@ module RSpock
       def capture_name    = capture_var&.children&.[](0)
     end
 
-    class InteractionNode < Node
+    class InteractionNode < ASTTransform::Node
       register :rspock_interaction
 
       def cardinality  = children[0]
@@ -101,7 +92,7 @@ module RSpock
       def block_pass   = children[5]
     end
 
-    class BinaryStatementNode < Node
+    class BinaryStatementNode < ASTTransform::Node
       register :rspock_binary_statement
 
       def lhs      = children[0]
@@ -109,23 +100,11 @@ module RSpock
       def rhs      = children[2]
     end
 
-    class StatementNode < Node
+    class StatementNode < ASTTransform::Node
       register :rspock_statement
 
       def expression = children[0]
       def source     = children[1]
     end
-
-    module NodeBuilder
-      include ASTTransform::TransformationHelper
-
-      def s(type, *children)
-        if type.to_s.start_with?('rspock_')
-          Node.build(type, *children)
-        else
-          super
-        end
-      end
-    end
   end
 end

data/lib/rspock/ast/parser/block.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'ast_transform/transformation_helper'
 require 'rspock/ast/node'
 
 module RSpock
@@ -7,7 +8,7 @@ module RSpock
       class BlockError < StandardError; end
 
       class Block
-        include RSpock::AST::NodeBuilder
+        include ASTTransform::TransformationHelper
 
         # Constructs a new Block.
         #

data/lib/rspock/ast/parser/interaction_parser.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'ast_transform/transformation_helper'
 require 'rspock/ast/node'
 
 module RSpock
@@ -17,7 +18,7 @@ module RSpock
       #   [4] outcome      - nil if no >>, otherwise s(:rspock_stub_returns, value) or s(:rspock_stub_raises, *args)
       #   [5] block_pass   - nil if no &, otherwise s(:block_pass, ...)
       class InteractionParser
-        include RSpock::AST::NodeBuilder
+        include ASTTransform::TransformationHelper
 
         class InteractionError < RuntimeError; end
 
@@ -34,6 +35,10 @@ module RSpock
         def parse(node)
           return node unless interaction_node?(node)
 
+          # Anchor at the full interaction expression (including >> outcome), so the Mocha setup it lowers into is
+          # emitted at the interaction's line.
+          anchor = node
+
           if return_value_node?(node)
             outcome = parse_outcome(node.children[2])
             node = node.children[0]
@@ -45,7 +50,7 @@ module RSpock
           rhs = node.children[2]
           receiver, message, args, block_pass = parse_rhs(rhs)
 
-          s(:rspock_interaction,
+          interaction = s(:rspock_interaction,
             cardinality,
             receiver,
             s(:sym, message),
@@ -53,6 +58,8 @@ module RSpock
             outcome,
             block_pass
           )
+
+          anchor.loc&.expression ? s_at(anchor, interaction.type, *interaction.children) : interaction
         end
 
         private
@@ -101,8 +108,8 @@ module RSpock
 
         def parse_rhs(node)
           if node.type == :block
-            raise InteractionError, "Inline blocks (do...end / { }) are not supported in interactions @ #{range(node)}. " \
-              "Use &var for block forwarding verification, or << for method body override (future)."
+            raise InteractionError, "Inline blocks (do...end / { }) are not supported in interactions " \
+              "@ #{range(node)}. Use &var for block forwarding verification, or << for method body override (future)."
           end
 
           if node.type != :send

data/lib/rspock/ast/parser/statement_parser.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'ast_transform/transformation_helper'
 require 'rspock/ast/node'
 
 module RSpock
@@ -10,7 +11,7 @@ module RSpock
       # - Binary operators (==, !=, =~, etc.) become :rspock_binary_statement nodes.
       # - Everything else becomes :rspock_statement nodes with the original source text captured.
       class StatementParser
-        include RSpock::AST::NodeBuilder
+        include ASTTransform::TransformationHelper
 
         BINARY_OPERATORS = %i[== != =~ !~ > < >= <=].freeze
         ASSIGNMENT_TYPES = %i[lvasgn masgn op_asgn or_asgn and_asgn].freeze
@@ -44,10 +45,10 @@ module RSpock
           if node.type == :lvasgn
             variable = s(:sym, node.children[0])
             exception_class = node.children[1].children[2]
-            s(:rspock_raises, exception_class, variable)
+            s_anchored(node, :rspock_raises, exception_class, variable)
           else
             exception_class = node.children[2]
-            s(:rspock_raises, exception_class)
+            s_anchored(node, :rspock_raises, exception_class)
           end
         end
 
@@ -61,13 +62,20 @@ module RSpock
             BINARY_OPERATORS.include?(node.children[1])
         end
 
+        # RSpock IR nodes are anchored at the statement they classify, so the assertions they lower into are
+        # emitted at the statement's source line.
         def build_binary_statement(node)
-          s(:rspock_binary_statement, node.children[0], s(:sym, node.children[1]), node.children[2])
+          s_anchored(node, :rspock_binary_statement, node.children[0], s(:sym, node.children[1]), node.children[2])
         end
 
         def build_statement(node)
           source = node.loc&.expression&.source || node.inspect
-          s(:rspock_statement, node, s(:str, source))
+          s_anchored(node, :rspock_statement, node, s(:str, source))
+        end
+
+        # s_at that tolerates loc-less anchors (unit tests build synthetic ASTs).
+        def s_anchored(anchor, type, *children)
+          anchor.loc&.expression ? s_at(anchor, type, *children) : s(type, *children)
         end
       end
     end

data/lib/rspock/ast/parser/test_method_parser.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'ast_transform/transformation_helper'
 require 'rspock/ast/node'
 
 module RSpock
@@ -12,7 +13,7 @@ module RSpock
       #           s(:rspock_body, s(:rspock_given, ...), s(:rspock_when, ...), ...),
       #           s(:rspock_where, ...))   # optional
       class TestMethodParser
-        include RSpock::AST::NodeBuilder
+        include ASTTransform::TransformationHelper
 
         def initialize(block_registry, strict: true)
           @block_registry = block_registry
@@ -74,7 +75,8 @@ module RSpock
           end
 
           unless blocks.last.can_end?
-            raise BlockError, "Block #{blocks.last.type} @ #{blocks.last.range} must be followed by one of these Blocks: #{blocks.last.successors}"
+            raise BlockError, "Block #{blocks.last.type} @ #{blocks.last.range} " \
+              "must be followed by one of these Blocks: #{blocks.last.successors}"
           end
         end
 

data/lib/rspock/ast/statement_to_assertion_transformation.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'ast_transform/transformation_helper'
 require 'rspock/ast/node'
 
 module RSpock
@@ -8,7 +9,7 @@ module RSpock
     # Binary statements dispatch to specialized assertions (assert_equal, assert_match, assert_operator).
     # General statements use assert_equal(true/false, expr, source_message) with negation detection.
     class StatementToAssertionTransformation
-      include RSpock::AST::NodeBuilder
+      include ASTTransform::TransformationHelper
 
       BINARY_DISPATCH = {
         :==  => :assert_equal,

data/lib/rspock/ast/test_method_def_transformation.rb

@@ -4,15 +4,16 @@ require 'rspock/ast/test_method_dstr_transformation'
 
 module RSpock
   module AST
+    # Appends the data row's index and source line to a Where-driven test's name. The values arrive through
+    # internal block parameters on the row iterator (see TestMethodTransformation#build_where_args) and surface in
+    # the test NAME only: the name is what makes identical data rows unique and what the -n selector matches to
+    # isolate a row. They are deliberately not exposed as test-scope variables.
     class TestMethodDefTransformation < ASTTransform::AbstractTransformation
-      TEST_INDEX_AST = s(:begin,
-                         s(:lvar, :_test_index_))
-
-      LINE_NUMBER_AST = s(:begin,
-                         s(:lvar, :_line_number_))
-
-      SPACE_STR_AST = s(:str, " ")
+      ROW_INDEX_ARG = :__rspock_row_index__
+      ROW_LINE_ARG = :__rspock_row_line__
 
+      ROW_INDEX_AST = s(:begin, s(:lvar, ROW_INDEX_ARG))
+      ROW_LINE_AST = s(:begin, s(:lvar, ROW_LINE_ARG))
       LINE_NUMBER_STR_AST = s(:str, " line ")
 
       def run(node)
@@ -23,7 +24,7 @@ module RSpock
 
       def on_str(node)
         merged = s(:str, "#{node.children[0]} ")
-        node.updated(:dstr, [merged, TEST_INDEX_AST, LINE_NUMBER_STR_AST, LINE_NUMBER_AST])
+        node.updated(:dstr, [merged, ROW_INDEX_AST, LINE_NUMBER_STR_AST, ROW_LINE_AST])
       end
 
       def on_dstr(node)