rspock 2.5.0 → 3.0.0

data/lib/rspock/ast/test_method_dstr_transformation.rb

@@ -3,15 +3,13 @@ require 'ast_transform/abstract_transformation'
 
 module RSpock
   module AST
+    # dstr counterpart of TestMethodDefTransformation: appends the row index and source line interpolations to an
+    # already-interpolated test name.
     class TestMethodDstrTransformation < ASTTransform::AbstractTransformation
-      TEST_INDEX_AST = s(:begin,
-                         s(:lvar, :_test_index_))
-
-      LINE_NUMBER_AST = s(:begin,
-                          s(:lvar, :_line_number_))
+      ROW_INDEX_AST = s(:begin, s(:lvar, :__rspock_row_index__))
+      ROW_LINE_AST = s(:begin, s(:lvar, :__rspock_row_line__))
 
       SPACE_STR_AST = s(:str, " ")
-
       LINE_NUMBER_STR_AST = s(:str, " line ")
 
       def on_dstr(node)
@@ -24,7 +22,7 @@ module RSpock
           children << SPACE_STR_AST
         end
 
-        children.push(TEST_INDEX_AST, LINE_NUMBER_STR_AST, LINE_NUMBER_AST)
+        children.push(ROW_INDEX_AST, LINE_NUMBER_STR_AST, ROW_LINE_AST)
         node.updated(nil, children)
       end
     end

data/lib/rspock/ast/test_method_transformation.rb

@@ -5,7 +5,6 @@ require 'rspock/ast/statement_to_assertion_transformation'
 require 'rspock/ast/header_nodes_transformation'
 require 'rspock/ast/interaction_to_mocha_mock_transformation'
 require 'rspock/ast/interaction_to_block_identity_assertion_transformation'
-require 'rspock/ast/method_call_to_lvar_transformation'
 require 'rspock/ast/test_method_def_transformation'
 require 'rspock/ast/parser/test_method_parser'
 
@@ -26,158 +25,208 @@ module RSpock
       private
 
       def transform(rspock_ast)
-        hoisted_setups = []
-
         method_call = rspock_ast.def_node.method_call
         method_args = rspock_ast.def_node.args
         where = rspock_ast.where_node
 
-        transformed_blocks = rspock_ast.body_node.children.map do |block_node|
-          case block_node.type
-          when :rspock_then
-            transform_then_block(block_node, hoisted_setups)
-          when :rspock_expect
-            transform_expect_block(block_node)
-          else
-            block_node
-          end
+        body = build_test_body(rspock_ast.body_node)
+        build_ruby_ast(method_call, method_args, body, where)
+      end
+
+      # --- Test body assembly ---
+      #
+      # Statements are assembled in SOURCE order so line-aligned emission keeps each one on its own line.
+      # Execution-order requirements that source order cannot express (interaction setups in Then must run before the
+      # When body they observe) are carried by ast-transform's thunk facility (run_after / thunk) instead of by
+      # textual hoisting.
+      def build_test_body(body_node)
+        blocks = body_node.children
+        sections = blocks.map { |block_node| transform_block(block_node) }
+
+        when_statements = statements_of_type(blocks, sections, :rspock_when)
+        cleanup_statements = statements_of_type(blocks, sections, :rspock_cleanup)
+        interaction_setups = sections.flat_map(&:interaction_setups)
+        raises_node = blocks.filter_map { |block_node| find_raises(block_node) }.first
+
+        source_order = blocks.zip(sections).flat_map do |block_node, section|
+          next [] if block_node.type == :rspock_cleanup
+
+          section.statements.reject { |statement| statement.type == :rspock_raises }
         end
 
-        transformed_body = rspock_ast.body_node.updated(nil, transformed_blocks)
-        build_ruby_ast(method_call, method_args, transformed_body, where, hoisted_setups)
-      end
+        body_children = order_execution(source_order, when_statements, interaction_setups, raises_node)
 
-      def transform_then_block(then_node, hoisted_setups)
-        interaction_setups = []
-        then_children = []
+        ast = s(:begin, *body_children)
+        cleanup_statements.empty? ? ast : s(:kwbegin, s(:ensure, ast, s(:begin, *cleanup_statements)))
+      end
 
-        then_node.children.each_with_index do |child, idx|
-          if child.type == :rspock_interaction
-            setup = InteractionToMochaMockTransformation.new(idx).run(child)
-            assertion = InteractionToBlockIdentityAssertionTransformation.new(idx).run(child)
+      Section = Data.define(:statements, :interaction_setups)
 
-            interaction_setups << setup
-            then_children << assertion unless assertion.equal?(child)
-          else
-            then_children << transform_statement_or_passthrough(child)
-          end
+      def transform_block(block_node)
+        case block_node.type
+        when :rspock_then, :rspock_expect
+          transform_assertion_block(block_node)
+        else
+          Section.new(statements: block_node.children, interaction_setups: [])
         end
+      end
 
-        unless interaction_setups.empty?
-          interaction_setups.each do |node|
-            if node.type == :begin
-              hoisted_setups.concat(node.children)
-            else
-              hoisted_setups << node
-            end
+      # Then/Expect children become plain Ruby in place: interactions lower to Mocha setups anchored at the
+      # interaction's own source line (plus an identity assertion for &block forwarding), statements become
+      # assertions at their own lines.
+      #
+      # Within the section, ALL setups come before all assertions: the thunked When body executes right after the
+      # last setup, and every assertion (identity or otherwise) observes the When body's effects, so none may
+      # precede that point. Setups keep source order and their anchors, so alignment holds; assertions after them
+      # are either synthetic (identity assertions, loc-less, pack anywhere) or textually below the interactions in
+      # the common case.
+      def transform_assertion_block(block_node)
+        setups = []
+        assertions = []
+        interaction_index = 0
+
+        block_node.children.each do |child|
+          case child.type
+          when :rspock_interaction
+            interaction_setups, identity_assertions = lower_interaction(child, interaction_index)
+            interaction_index += 1
+            setups.concat(interaction_setups)
+            assertions.concat(identity_assertions)
+          when :rspock_binary_statement, :rspock_statement
+            assertions << anchored_at(child, @statement_transformation.run(child))
+          else
+            assertions << child
           end
         end
 
-        then_node.updated(nil, then_children)
+        Section.new(statements: setups + assertions, interaction_setups: setups)
       end
 
-      def transform_expect_block(expect_node)
-        new_children = expect_node.children.map { |child| transform_statement_or_passthrough(child) }
-        expect_node.updated(nil, new_children)
+      # @return [Array(Array, Array)] Mocha setup statements, identity assertions
+      def lower_interaction(interaction, index)
+        setup = InteractionToMochaMockTransformation.new(index).run(interaction)
+        assertion = InteractionToBlockIdentityAssertionTransformation.new(index).run(interaction)
+
+        setups = setup.type == :begin ? setup.children.dup : [setup]
+        setups[0] = anchored_at(interaction, setups[0])
+
+        [setups, assertion.equal?(interaction) ? [] : [assertion]]
       end
 
-      def transform_statement_or_passthrough(child)
-        case child.type
-        when :rspock_binary_statement, :rspock_statement
-          @statement_transformation.run(child)
+      # Reorders execution (not text) where required:
+      # - interactions without raises: run the When body after the last interaction setup (run_after — the paved
+      #   road).
+      # - raises without interactions: the When body inlines directly into assert_raises; no thunk needed.
+      # - raises with interactions: the When body is thunked into the assert_raises block inserted after the last
+      #   setup; the lowering re-emits the body at its own source lines.
+      def order_execution(source_order, when_statements, interaction_setups, raises_node)
+        if raises_node
+          build_raises_body(source_order, when_statements, interaction_setups, raises_node)
+        elsif interaction_setups.any? && when_statements.any?
+          run_after(source_order, run: when_statements, after: interaction_setups.last)
         else
-          child
+          source_order
         end
       end
 
-      # --- Build final Ruby AST ---
-
-      def build_ruby_ast(method_call, method_args, body_node, where, hoisted_setups)
-        if where
-          test_def = s(:block,
-            TestMethodDefTransformation.new.run(method_call),
-            method_args,
-            build_test_body(body_node, hoisted_setups)
-          )
-          test_def = HeaderNodesTransformation.new(where.header).run(test_def)
+      def build_raises_body(source_order, when_statements, interaction_setups, raises_node)
+        if interaction_setups.any?
+          assertion = build_assert_raises(raises_node, thunk(*when_statements))
 
-          s(:block,
-            build_where_iterator(where.data_rows),
-            build_where_args(where.header),
-            test_def
-          )
+          reordered = replace_run(source_order, when_statements, [])
+          insert_after(reordered, interaction_setups.last, assertion)
         else
-          s(:block,
-            method_call,
-            method_args,
-            build_test_body(body_node, hoisted_setups)
-          )
+          when_body = when_statements.length == 1 ? when_statements[0] : s(:begin, *when_statements)
+          assertion = build_assert_raises(raises_node, when_body)
+
+          replace_run(source_order, when_statements, [assertion])
         end
       end
 
-      def build_test_body(body_node, hoisted_setups)
-        body_children = []
-        blocks = body_node.children
+      def build_assert_raises(raises_node, body)
+        assert_raises_call = s(:block,
+          s(:send, nil, :assert_raises, raises_node.exception_class),
+          s(:args),
+          body
+        )
 
-        blocks.each_with_index do |block_node, i|
-          case block_node.type
-          when :rspock_given
-            body_children.concat(block_node.children)
-          when :rspock_when
-            body_children.concat(hoisted_setups)
-            raises_node = find_raises_in_next_then(blocks, i)
-
-            if raises_node
-              body_children << build_assert_raises(block_node, raises_node)
-            else
-              body_children.concat(block_node.children)
-            end
-          when :rspock_then, :rspock_expect
-            block_node.children.each do |child|
-              body_children << child unless child.type == :rspock_raises
-            end
-          when :rspock_cleanup
-            # handled below as ensure
-          end
+        if raises_node.capture_name
+          s(:lvasgn, raises_node.capture_name, assert_raises_call)
+        else
+          assert_raises_call
         end
+      end
 
-        ast = s(:begin, *body_children)
+      def find_raises(block_node)
+        return nil unless block_node.type == :rspock_then
 
-        cleanup = body_node.children.find { |n| n.type == :rspock_cleanup }
-        if cleanup && !cleanup.children.empty?
-          ensure_node = s(:begin, *cleanup.children)
-          ast = s(:kwbegin, s(:ensure, ast, ensure_node))
-        end
+        block_node.children.find { |child| child.type == :rspock_raises }
+      end
 
-        MethodCallToLVarTransformation.new(:_test_index_, :_line_number_).run(ast)
+      def statements_of_type(blocks, sections, type)
+        blocks.zip(sections)
+          .select { |block_node, _section| block_node.type == type }
+          .flat_map { |_block_node, section| section.statements }
       end
 
-      # --- Raises condition helpers ---
+      # --- Identity-based sequence edits (non-thunk counterparts of run_after) ---
 
-      def find_raises_in_next_then(blocks, current_index)
-        next_block = blocks[current_index + 1]
-        return nil unless next_block&.type == :rspock_then
+      def replace_run(statements, run, replacement)
+        start = statements.index { |statement| statement.equal?(run.first) }
+        raise ArgumentError, "run is not part of statements" unless start
 
-        next_block.children.find { |c| c.type == :rspock_raises }
+        result = statements.dup
+        result[start, run.length] = replacement
+        result
       end
 
-      def build_assert_raises(when_node, raises_node)
-        when_body = when_node.children.length == 1 ? when_node.children[0] : s(:begin, *when_node.children)
+      def insert_after(statements, anchor, insertion)
+        index = statements.index { |statement| statement.equal?(anchor) }
+        raise ArgumentError, "anchor is not part of statements" unless index
 
-        assert_raises_call = s(:block,
-          s(:send, nil, :assert_raises, raises_node.exception_class),
-          s(:args),
-          when_body
-        )
+        result = statements.dup
+        result.insert(index + 1, insertion)
+        result
+      end
 
-        if raises_node.capture_name
-          s(:lvasgn, raises_node.capture_name, assert_raises_call)
+      # Re-anchors +node+ at +anchor+'s source location so emission places it on the anchor's line.
+      # No-op for anchors without locations.
+      def anchored_at(anchor, node)
+        return node unless anchor.loc&.expression
+
+        s_at(anchor, node.type, *node.children)
+      end
+
+      # --- Build final Ruby AST ---
+
+      def build_ruby_ast(method_call, method_args, body_node, where)
+        if where
+          test_def = anchored_at(method_call, s(:block,
+            TestMethodDefTransformation.new.run(method_call),
+            method_args,
+            body_node
+          ))
+          test_def = HeaderNodesTransformation.new(where.header).run(test_def)
+
+          s(:block,
+            build_where_iterator(where.data_rows),
+            build_where_args(where.header),
+            test_def
+          )
         else
-          assert_raises_call
+          anchored_at(method_call, s(:block,
+            method_call,
+            method_args,
+            body_node
+          ))
         end
       end
 
       # --- Where block helpers ---
+      #
+      # Each data row carries its source line as a trailing element, surfaced in the generated test NAME only
+      # (uniqueness for identical rows + the -n selector target) through internal block parameters. There is no
+      # user-facing runtime variable: isolate a row by running its generated test by name, then break normally.
 
       def build_where_iterator(data_rows)
         s(:send,
@@ -192,15 +241,16 @@ module RSpock
       def build_where_data_row(row)
         children = row.dup
         children << s(:int, row.first&.loc&.expression&.line)
-        s(:array, *children)
+        anchor = row.first
+        anchor&.loc&.expression ? s_at(anchor, :array, *children) : s(:array, *children)
       end
 
       def build_where_args(header)
         injected_args = header.map { |column| s(:arg, column) }
-        injected_args << s(:arg, :_line_number_)
+        injected_args << s(:arg, TestMethodDefTransformation::ROW_LINE_ARG)
         s(:args,
           s(:mlhs, *injected_args),
-          s(:arg, :_test_index_),
+          s(:arg, TestMethodDefTransformation::ROW_INDEX_ARG),
         )
       end
     end

data/lib/rspock/ast/transformation.rb

@@ -77,8 +77,7 @@ module RSpock
 
       def process_rspock(node)
         processed = process_all(node).compact
-        children = [source_map_rescue_wrapper(s(:begin, *[EXTEND_RSPOCK_DECLARATIVE, *processed]))]
-        node.updated(nil, children)
+        node.updated(nil, [EXTEND_RSPOCK_DECLARATIVE, *processed])
       end
 
       def on_block(node)
@@ -91,31 +90,6 @@ module RSpock
           strict: @strict
         ).run(node)
       end
-
-      def source_map_rescue_wrapper(node)
-        s(:kwbegin,
-          s(:rescue,
-            node,
-            s(:resbody,
-              s(:array,
-                s(:const, nil, :StandardError)
-              ),
-              s(:lvasgn, :e),
-              s(:begin,
-                s(:send,
-                  s(:send,
-                    s(:const,
-                      s(:const,
-                        s(:cbase), :RSpock), :BacktraceFilter), :new), :filter_exception,
-                  s(:lvar, :e)
-                ),
-                s(:send, nil, :raise)
-              )
-            ),
-            nil
-          )
-        )
-      end
     end
   end
 end

data/lib/rspock/version.rb

@@ -1,3 +1,3 @@
 module RSpock
-  VERSION = "2.5.0"
+  VERSION = "3.0.0"
 end

data/lib/rspock.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 require 'rspock/version'
 
-require 'rspock/backtrace_filter'
 require 'rspock/declarative'
 
 require 'ast_transform'

data/rspock.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   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"
@@ -31,9 +31,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "simplecov", "~> 0.22"
 
   # Runtime dependencies
-  spec.add_runtime_dependency "ast_transform", "~> 2.0"
+  # parser and unparser are used only through ast_transform, which owns their floors.
+  spec.add_runtime_dependency "ast_transform", "~> 3.0"
   spec.add_runtime_dependency "minitest", "~> 5.0"
   spec.add_runtime_dependency "mocha", ">= 1.0"
-  spec.add_runtime_dependency "parser", ">= 3.0"
-  spec.add_runtime_dependency "unparser", ">= 0.6"
 end

data/skills/rspock/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: rspock
+description: >-
+  MUST be used when writing or modifying Minitest tests in any repo using
+  rspock (look for transform!(RSpock::AST::Transformation) in test files or
+  rspock in the Gemfile). RSpock rewrites test semantics via AST
+  transformation — code that looks like a no-op statement is an assertion,
+  and Minitest habits produce silently wrong tests.
+---
+
+# RSpock: writing tests
+
+RSpock is a Spock-inspired testing framework on top of Minitest. Tests are
+valid Ruby syntax with **different semantics**, applied by AST
+transformation at load time. Do not reason about these files as plain
+Minitest.
+
+## The invariant that must never be violated
+
+**Inside a `transform!(RSpock::AST::Transformation)` class, every bare
+statement in a `Then`/`Expect` block IS an assertion. Outside one, it is
+NOT — it evaluates and silently discards.**
+
+Consequences:
+
+- Inside a `transform!` class, write expression assertions — `a == b` in a
+  Then/Expect block. The transform compiles them to assertions with proper
+  failure messages; the Minitest assert API is not the dialect here.
+- In a plain Minitest class, use the assert API (`assert_equal` and
+  friends). A bare comparison there evaluates and discards — a silently
+  green test.
+- When editing a test file, first check for the `transform!` line at each
+  class definition; it decides which dialect that class speaks. Both
+  styles may legitimately coexist in one file (see `strict: false` below)
+  — match the dialect of the class you are in.
+
+## Boilerplate
+
+```ruby
+require "test_helper"
+
+transform!(RSpock::AST::Transformation)
+class MyThingTest < Minitest::Test
+  test "descriptive name" do
+    # code blocks here
+  end
+end
+```
+
+The application must install the hook once (usually in the test helper):
+`require "ast_transform"; ASTTransform.install`. That is the whole setup —
+Rails apps need nothing extra (backtraces and debuggers are source-true by
+construction; there is no backtrace cleaner to configure). Mixed files can
+use `transform!(RSpock::AST::Transformation.new(strict: false))` to allow
+plain Minitest tests alongside — this exists to ease gradual migration,
+so treat mixed files as normal, not as something to unify.
+
+The transform is an abstraction — trust it. If you ever need to see the
+compiled Ruby (debugging only, never as routine verification), the
+transformed files are written under `tmp/ast_transform/<relative path>`;
+they are emitted line-aligned, so their line numbers match your source
+exactly.
+
+## Code blocks and their order
+
+`Given` (setup) → `When` (stimulus) → `Then` (response), or `Expect`
+(stimulus+response in one), plus `Cleanup` (always runs; code defensively
+with `&.`) and `Where` (data table, last in source but evaluated first).
+Every block takes an optional description string. A `When` is always
+followed by a `Then`. Use When+Then for side-effecting code, Expect for
+pure functions.
+
+## Assertion forms (Then/Expect)
+
+```ruby
+Then "the walk produced the right state"
+actual == expected            # binary operators: == != =~ !~ > < >= <=
+list.include?(x)              # bare boolean expression asserts
+!cart.empty?                  # negation asserts
+name = actual.first           # assignments pass through (not assertions)
+```
+
+LHS is actual, RHS is expected. Exception assertions live in Then, apply
+to the preceding When, one per block:
+
+```ruby
+Then "a parse error names the token"
+e = raises JSON::ParserError   # capture optional
+e.message.include?("unexpected token")
+```
+
+`raises` is not supported in Expect blocks.
+
+## Where tables (data-driven)
+
+```ruby
+test "adding #{a} and #{b} gives #{c}" do
+  Expect
+  a + b == c
+
+  Where
+  a  | b  | c
+  -1 | 1  | 0
+  0  | 0  | 0
+  1  | 2  | 3
+end
+```
+
+Header names become local variables and interpolate into the test name.
+The table is evaluated in class scope — it cannot see instance methods or
+test-local variables. Order rows like a truth table; rightmost column is
+the expected result.
+
+To generate an exhaustive table instead of writing it by hand:
+
+```
+rake rspock:truth_table -- a=-1,0,1 b=-1,0,1 expected_result="'?'"
+```
+
+It emits the formatted cross-product (fill the `'?'` column manually).
+Escape commas inside a value with `\,` (e.g. `b="gen(1\, 2)","gen(3\, 4)"`).
+Non-Rails projects must load the gem's Rakefile once to get the task —
+see the README's installation section.
+
+## Interaction mocking (Then only)
+
+```ruby
+Then
+1 * subscriber.receive("hello")                 # exactly one call
+0 * mailer.deliver                              # must never be called
+(1..3) * poller.tick                            # between one and three
+(1.._) * poller.tick                            # at least once
+(_..3) * poller.tick                            # at most three times
+_ * cache.fetch("key") >> cached                # any count, stubbed return
+1 * repo.find(42) >> raises(RecordNotFound)     # stubbed exception
+1 * ui.frame("Build", &my_block)                # block-identity check
+```
+
+Declared in Then but installed before When runs — declare naturally,
+RSpock handles ordering. Compiles to Mocha. Inline blocks (`{ }` /
+`do...end`) are not allowed in interactions — use a named proc with `&`.
+Mocks never yield blocks by design: needing that signals the unit under
+test is doing too much — restructure so the mock boundary sits between
+responsibilities.
+
+## Debugging failures
+
+- Backtraces AND debugger display are source-true: transformed code is
+  emitted with every statement on its original source line, so line
+  numbers point at the file you wrote with no mapping layer. Trust them;
+  don't second-guess against `tmp/ast_transform/`.
+- `break file:line` binds on user statements; interactive debuggers show
+  your real source. One documented oddity: interaction setups execute
+  before the When body, so stepping through a test with interactions
+  jumps from the interaction lines back up to the When line once.
+- To isolate a Where row: the generated test name embeds the row's index
+  and source line (e.g. `... 1 line 15`). For a newly failing row, copy
+  the rerun command printed with the failure and add a plain
+  `binding.pry`. For a chosen row, run `-n /line_15/` with the line from
+  the editor gutter, or break conditionally on the column locals
+  themselves (`binding.pry if input == "not json"`). A source-line
+  breakpoint on a data row cannot isolate its run — the table evaluates
+  once, in class scope; name-selection is the mechanism.
+
+## Pitfalls (wrong → right)
+
+```ruby
+# WRONG: Minitest API inside an RSpock class
+assert_equal 3, add(1, 2)
+# RIGHT
+Expect
+add(1, 2) == 3
+```
+
+```ruby
+# WRONG: bare comparison in a class without transform! — silently green
+class FooTest < Minitest::Test
+  test("x") { compute == 42 }
+end
+# RIGHT: add transform!(RSpock::AST::Transformation) above the class,
+# or use assert_equal in plain Minitest
+```
+
+```ruby
+# WRONG: Where table using an instance method for column data
+Where
+input        | expected
+helper_val   | 1        # NameError: class scope
+# RIGHT: use class methods or literals in Where rows
+```
+
+```ruby
+# WRONG: expecting a mocked method to yield
+1 * ui.with_spinner("work") { drain(io) }
+# RIGHT: restructure — mock boundary between responsibilities
+success = drain(io)   # test with a real StringIO
+1 * ui.ok("work")     # simple expectation, no block
+```