rspec-mergify 2026.10.6 → 2026.10.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06c5a8599786bb57121e965e20ef522113020086322e1d31367623a52cc93fb5
-  data.tar.gz: 035ef91fee443aa985ba16ed224a16a0b5b5801fe93949dc60e69afdaf8836a6
+  metadata.gz: e5715b89995827b7f5d3840e0c3c1d94288f511fedcac9f3bdd58433c1908228
+  data.tar.gz: d70082926c396a3ac69ae778f9024be9d3cde6570cd84ef498d1e489ae9164d2
 SHA512:
-  metadata.gz: 5e41ff044db2dab090c398ff6e98c65c479b2a633d98e349399d995ab6b2f5935a2dcd8d4bddb3928821083351bc0cc50855baf96073a1285c5e16fd1429f6c8
-  data.tar.gz: 602b67361d3d62c42d53a7a9a6dcc236a2c8a93d2a6559984d76374e9f72ad4fc939b5857a7eb241c55381d32edcddeb4379075c792534f8aedb822eed05307d
+  metadata.gz: 036d1307e6752c12f0c4a88a5f4625528a8ef6eb7d0247b23100127d42a1842c2a3ddadcffc2439f27bb73f49f71d478346fb51b4a1524725c6812f232e10168
+  data.tar.gz: d3e25b1c4dda733655435cd3e28016a30127c82ed04e8d5b8e07a8e0e7c7374d572491bf8559e3f6c9262c814abe5130e4b65781b0c93cd7f91f2a72f5496de8

data/README.md

@@ -7,7 +7,7 @@ RSpec plugin for [Mergify Test Engine](https://docs.mergify.com/test-engine/).
 - **Test tracing** — Sends OpenTelemetry traces for every test to Mergify's API
 - **Flaky test detection** — Intelligently reruns tests to detect flakiness with budget constraints
 - **Test quarantine** — Quarantines failing tests so they don't block CI
-- **Test selection** — Runs only the previously-failing examples when Mergify's merge queue reruns a job
+- **Test selection** — Runs first the examples a merge-queue bisection step failed in the step above, and stops once one fails again
 
 ## Installation
 
@@ -21,7 +21,7 @@ Then run `bundle install`.
 
 ### Supported platforms
 
-The gem ships precompiled, so nothing is built on your machine. Each platform gem carries an extension for Ruby 3.1 through 4.0:
+The gem runs on `mergify-ci-core`, which Bundler installs with it. That gem ships precompiled, so nothing is built on your machine. Each of its platform gems carries an extension for Ruby 3.1 through 4.0:
 
 | Platform | Requirement |
 |---|---|
@@ -52,7 +52,7 @@ The plugin activates automatically when running in CI (detected via the `CI` env
 | `MERGIFY_CI_DEBUG` | Print the session verdict and the spans instead of sending them, and upload nothing | `false` |
 | `MERGIFY_TRACEPARENT` | W3C distributed trace context | — |
 | `MERGIFY_TEST_JOB_NAME` | Mergify test job name | — |
-| `MERGIFY_TEST_SELECTION_ENABLE` | Opt this job into test selection (see below) | `false` |
+| `MERGIFY_FAIL_FIRST_ENABLE` | Set to `false` to never run first what a merge-queue bisection step of this job failed before | `true` |
 
 The names these replace, `RSPEC_MERGIFY_ENABLE` and `RSPEC_MERGIFY_DEBUG`, are
 deprecated: they still work when the new name is not set, and the summary says
@@ -61,61 +61,84 @@ them: `RSPEC_MERGIFY_DEBUG=false` leaves debug off.
 
 ### Test selection
 
-When Mergify's merge queue reruns a job — a retry, or a step of a batch
-bisection — only the examples that failed on the previous attempt are
-informative. The gem asks Mergify whether the current run is such a rerun and,
-if so, runs only those examples.
-
-**This is off until you turn it on, per job.** Set
-`MERGIFY_TEST_SELECTION_ENABLE=true` on the job you want reduced. Installing the
-gem is not enough — a feature that decides not to run tests starts only where
-you wrote that it should. Anything that is not a recognised yes (unset, empty,
-`false`, unparsable) means no, and a job that has not opted in never asks.
-
-Once opted in, it only ever removes work:
-
-- the answer is applied **after** RSpec's own filters — file and line
-  arguments, `--tag`, `-e`, `--only-failures` all still narrow the run, never
-  widen it;
-- examples are matched by their id (`./spec/models/user_spec.rb[1:2]`), the
-  identity RSpec itself reruns failures by;
-- if Mergify says the previous attempt already ran every one of these examples
-  and they passed, the run executes none and exits green;
-- if any example Mergify asks for is not collected here, the full suite runs;
-- any error, timeout, or unrecognised answer runs the full suite;
-- if Mergify refuses to pick a previous attempt (several runs of this job
-  report under one name), the run **fails** with Mergify's explanation: give
-  each run its own `MERGIFY_TEST_JOB_NAME`;
-- at the end of the run the gem sends Mergify what it concluded (the counts
-  and the failing examples) — unless the run failed outside any example (a
-  failing `after(:context)` or suite hook), in which case a retry runs the
-  full suite.
-
-Each parallel_tests worker, and each CI job handed a slice of the spec files,
-is matched to the same slice of the previous attempt, by the examples it
-collects. This needs the slices to be the same on both attempts, which is the
-case for a split by file size or by a committed runtime log; Knapsack Pro's
-Queue Mode hands files out dynamically and is not supported.
-
-#### Bisection steps: failures first
-
-When the merge queue splits a failed batch, a test that passed with every pull
-request of the batch can fail with only some of them, so a bisection step is
-never reduced: it runs its full suite. Mergify may instead tell it to run first
-the examples this job failed in the run the step was split from. The top-level
-groups holding them run first, and inside each group they run before its other
-examples and child groups — whatever the order (`--order rand`, `config.order`,
-your own `register_ordering`, `order:` metadata), which still applies to
-everything else. RSpec runs a group's whole subtree before the next group, and a
-group's own examples before its child groups, so when they span several groups
-the rest of each of those groups runs in between. If one of them fails again,
-the step is red whatever the rest does, so the run stops once they have all run
+When Mergify's merge queue splits a failed batch, each bisection step only
+needs to tell whether it is red. The gem asks Mergify whether the current run
+is such a step and, if so, runs first the examples this job failed in the run
+the step was split from (Fail First). The top-level groups holding them run
+first, and inside each group they run before its other examples and child
+groups — whatever the order (`--order rand`, `config.order`, your own
+`register_ordering`, `order:` metadata), which still applies to everything
+else. RSpec runs a group's whole subtree before the next group, and a group's
+own examples before its child groups, so when they span several groups the
+rest of each of those groups runs in between. If one of them fails again, the
+step is red whatever the rest does, so the run stops once they have all run
 (exit code 1, the remaining examples not run) and the queue can split again
 without waiting for the suite. If none fails again, the rest of the suite runs
 as usual. No example is ever skipped, so a green step still comes from a full
 suite. A quarantined failure does not stop the run; a `--fail-fast` of your own
 still stops at the first failure.
 
+**It is on by default.** A job that must always run its suite in its usual
+order sets `MERGIFY_FAIL_FIRST_ENABLE=false`, and never asks. Only a recognised
+no (`false`, `no`, `off`, `0`) turns it off. `MERGIFY_TEST_SELECTION_ENABLE`,
+its former name, is still read while the new one is unset or empty, and the
+summary at the end of the run says to switch. It is also enabled per
+organization on Mergify's side: until yours has it, every run is served the
+full suite, says nothing about it, and still sends
+its results, which show what Fail First would do there.
+
+It only ever asks in a build of a merge-queue batch, the only builds a
+bisection step can be: on GitHub Actions, the event of the draft pull request
+the queue opened; on any other build, the queue's git note on the branch, one
+`git ls-remote` against `origin` that runs while the tests are being collected.
+Every other build asks nothing and sends nothing. Of a batch's builds, only
+those below a failed batch, and not retrying their own checks, ask: the
+others cannot be a bisection step, and send their results only when the
+batch holds two pull requests or more, so a bisection step may read them, or
+when they failed. A build where git cannot answer (no `origin`, credentials
+the test step does not hold) asks, as it would without this.
+
+When it runs:
+
+- the order applies **after** RSpec's own filters — file and line arguments,
+  `--tag`, `-e`, `--only-failures` all still narrow the run;
+- examples are matched by the name Mergify knows them by (see
+  [Test names](#test-names));
+- any error, timeout, or unrecognised answer runs the full suite in its usual
+  order;
+- at the end of the run the gem sends Mergify what it concluded (the counts
+  and the failing examples) — unless the run failed outside any example (a
+  failing `after(:context)` or suite hook), in which case the next bisection
+  step runs its full suite in its usual order.
+
+Each parallel_tests worker, and each CI job handed a slice of the spec files,
+reports its own collection, by the examples it collects.
+
+### Test names
+
+Mergify knows each example by its file, its groups and its description:
+`spec/models/user_spec.rb > User > #full_name > joins first and last`. Adding,
+moving or removing an example renames no other. An example written without a
+description (`it { is_expected.to validate_presence_of(:email) }`) is named by
+its code, and examples a file names alike get their place after the name
+(`[1:2]`), as RSpec numbers them.
+
+Earlier releases named an example by its place instead
+(`./spec/models/user_spec.rb[1:2]`). A quarantine entry or a flaky-detection
+history under such a name still matches, but each example's history on the
+dashboard starts over under its new name. Quarantine an example again under
+its new name: an entry under its old one follows the place, so the example
+that holds it changes when one is added above.
+
+A suite that reported through
+[rspec_junit_formatter](https://github.com/sj26/rspec_junit_formatter) and
+`mergify ci junit-process` keeps its quarantine entries and flaky-detection
+history the same way: an example is still matched under the name those
+uploads gave it (`spec.models.user_spec.User#full_name joins first and last`).
+An example written without a description gets that name only once it ran, so
+on the pull request that switches, flaky detection may take it for a new
+test.
+
 ### Parallel runs
 
 [parallel_tests](https://github.com/grosser/parallel_tests) and [turbo_tests](https://github.com/serpapi/turbo_tests) need no setup. Each worker is a separate RSpec process, and each reports to Mergify as its own session:
@@ -147,8 +170,10 @@ bundle install
 bundle exec rake test
 ```
 
-`rake test` compiles the extension in Cargo's dev profile first: running
-`rspec` alone skips every binding example when the extension isn't built.
+`rake test` compiles `mergify-ci-core`'s extension in Cargo's dev profile
+first, with that gem's own bundle (`clients/mergify-ci-core`, `bundle install`
+there too): running `rspec` alone skips every binding example when the
+extension isn't built.
 
 ### Linting
 

data/THIRD_PARTY_LICENSES

@@ -8357,7 +8357,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 Community Data License Agreement Permissive 2.0 (CDLA-Permissive-2.0)
 
 Used by:
-  - webpki-root-certs 1.0.10 (https://github.com/rustls/webpki-roots)
+  - webpki-root-certs 1.0.11 (https://github.com/rustls/webpki-roots)
 
 # Community Data License Agreement - Permissive - Version 2.0
 

data/lib/mergify/rspec/configuration.rb

@@ -40,25 +40,21 @@ module Mergify
           # Also when the native extension did not load, which nothing can
           # tell apart from a run outside CI: the summary then says why it
           # reports nothing.
-          config.prepend_before(:suite) { Configuration.attach_formatter(config) } if reports? || !Native.available?
+          if reports? || !Mergify::CI::Core::Native.available?
+            config.prepend_before(:suite) { Configuration.attach_formatter(config) }
+          end
 
           # Flaky detection: prepared for every example of the run.
           config.before(:suite) do
             ci = Mergify::RSpec.test_run
             if ci
-              all_ids = ::RSpec.world.example_groups.flat_map(&:descendants).flat_map(&:examples).map(&:id)
-              ci.prepare_reruns(all_ids)
+              examples = ::RSpec.world.example_groups.flat_map(&:descendants).flat_map(&:examples)
+              names = ci.names
+              ci.prepare_reruns(examples.map { |example| names.of(example) },
+                                examples.to_h { |example| [names.of(example), names.formers(example)] })
             end
           end
 
-          # Quarantine: mark tests before execution
-          config.before(:each) do |example|
-            ci = Mergify::RSpec.test_run
-            next unless ci&.quarantined_tests&.include?(example.id)
-
-            example.metadata[:mergify_quarantined] = true
-          end
-
           # Each try of an example, which a retry plugin's loop (rspec-retry's)
           # makes inside the `around` hook below: the first `before` hook every
           # try runs, and the last `after` one.
@@ -81,12 +77,17 @@ module Mergify
             test_run&.reports? ? Configuration.run_example(example, test_run) : example.run
           end
 
-          # Quarantine: override failed quarantined test results. The failure is
-          # noted for flaky detection first, which would otherwise take a
-          # quarantined attempt that failed for one that passed.
+          # Quarantine: override failed quarantined test results. Asked once
+          # the example ran: one written without a description has the name a
+          # JUnit upload gave it only then, when RSpec has written it one from
+          # its matcher. The failure is noted for flaky detection first, which
+          # would otherwise take a quarantined attempt that failed for one
+          # that passed.
           config.after(:each) do |example|
-            next unless example.metadata[:mergify_quarantined] && example.exception
+            ci = Mergify::RSpec.test_run
+            next unless example.exception && ci&.quarantined_tests&.include?(ci.names.keys(example))
 
+            example.metadata[:mergify_quarantined] = true
             example.metadata[:mergify_quarantined_failure] = true
             example.metadata[:mergify_quarantined_exception] = example.exception
             example.instance_variable_set(:@exception, nil)
@@ -96,74 +97,39 @@ module Mergify
         end
       end
 
-      # Hand the session what this process is about to run, and apply what it
-      # decided: leave out what it does not keep, put first what a bisection
-      # step answered, or stop a refused run.
+      # Hand the session what this process is about to run, and put first
+      # what a bisection step answered.
       #
       # A `before(:suite)` hook, because that is the first moment RSpec has both
       # loaded the spec files and applied its filters, and the last one before
       # an example group starts. What each group runs is read from
       # `RSpec.world.filtered_examples`, which RSpec memoized while counting the
-      # run; narrowing those lists is what deselects.
+      # run.
+      # rubocop:disable-next Metrics/MethodLength
       def select_examples
         ci = Mergify::RSpec.test_run
         return unless ci
 
-        groups, examples = collected
-        decision = ci.select(examples.map(&:id))
-        apply_decision(ci, decision, groups, examples) if decision
+        examples = collected
+        names = ci.names
+        return unless ci.select(examples.map { |example| names.of(example) })
+
+        # Ordered, not filtered: a served example this run did not collect is
+        # expected -- a parallel worker holds part of the job's failures.
+        fail_first = ci.fail_first
+        FailureFirst.apply(fail_first, examples, names, reporter: ::RSpec.configuration.reporter) if fail_first
       rescue StandardError => e
         # This runs on every CI run, opted in or not, and RSpec would answer a
         # raise here by running nothing: a fault of this gem must cost the run
-        # its reduction, never its tests.
+        # its order, never its tests.
         ::RSpec.configuration.error_stream.puts(
-          "Mergify Test Selection failed, so the full suite runs: #{e.class}: #{e.message}"
+          "Mergify could not apply Fail First, so the full suite runs: #{e.class}: #{e.message}"
         )
       end
 
-      # Every group, and the examples RSpec will run of them, in its order.
+      # The examples RSpec will run, in its order.
       def collected
-        groups = ::RSpec.world.example_groups.flat_map(&:descendants)
-        [groups, groups.flat_map { |group| ::RSpec.world.filtered_examples[group] }]
-      end
-
-      def apply_decision(test_run, decision, groups, examples)
-        return refuse(decision['refusal']) if decision['refusal']
-
-        # Ordered, not filtered: a served example this run did not collect is
-        # expected -- a parallel worker holds part of the job's failures.
-        fail_first = test_run.fail_first
-        return run_failure_first(fail_first, examples) if fail_first
-
-        deselect(groups, decision['keep'].to_set) if decision['keep']
-      end
-
-      # Everything runs, the examples the step above failed first.
-      def run_failure_first(fail_first, examples)
-        FailureFirst.apply(fail_first, examples, reporter: ::RSpec.configuration.reporter)
-      end
-
-      # Stop the run before any example, the way RSpec stops one whose suite
-      # hook failed -- nothing runs, the exit code is red, and the summary
-      # counts an error outside of examples -- but with the server's
-      # explanation alone. Raised from the hook, the same failure is printed
-      # under a "Failure/Error:" header pointing at a line of this gem, which
-      # only buries the explanation.
-      def refuse(message)
-        ::RSpec.configuration.error_stream.puts("\n#{message}\n")
-        ::RSpec.world.wants_to_quit = true
-        reporter = ::RSpec.configuration.reporter
-        count = reporter.instance_variable_get(:@non_example_exception_count)
-        reporter.instance_variable_set(:@non_example_exception_count, count + 1) if count.is_a?(Integer)
-      end
-
-      # A group left with no example runs none of its `before(:context)`
-      # hooks: RSpec decides that from these same lists, once the group starts.
-      def deselect(groups, keep)
-        groups.each do |group|
-          ::RSpec.world.filtered_examples[group] =
-            ::RSpec.world.filtered_examples[group].select { |example| keep.include?(example.id) }
-        end
+        ::RSpec.world.example_groups.flat_map(&:descendants).flat_map { |group| ::RSpec.world.filtered_examples[group] }
       end
 
       # The reporter has sent `start` by the time suite hooks run, so the
@@ -182,13 +148,14 @@ module Mergify
       # tries a retry plugin makes after it, inside that run; flaky detection's
       # reruns follow, each a try alone.
       def run_example(example, test_run)
+        name = test_run.names.of(example)
         detector = test_run.flaky_detector
-        tries = run_first(example, test_run, detector)
-        return unless detector&.rerunning_test?(example.id)
+        tries = run_first(example, name, test_run, detector)
+        return unless detector&.rerunning_test?(name)
 
         initial_exception = example.exception
         first_failure = tries.failure || initial_exception
-        first_failure = rerun(example, detector, first_failure) if detector.start_reruns(example.id)
+        first_failure = rerun(example, name, detector, first_failure) if detector.start_reruns(name)
 
         # Which attempt decides the result is the session's rule: in 'new'
         # mode any failure fails the test, the retry plugin's tries included,
@@ -198,16 +165,15 @@ module Mergify
         example.example.instance_variable_set(:@exception, final_exception)
       end
 
-      # The example's first run: its first attempt, timed by the engine up to
-      # the second try where a retry plugin made one, then each try after it,
-      # handed to the session once the first reached flaky detection. What the
-      # first attempt was is kept for its span.
-      def run_first(example, test_run, detector)
-        id = example.id
-        detector&.attempt_started(id)
-        tries = run_tries(example) { detector&.attempt_stopped(id) }
-        detector&.attempt_ended(id, first_failed?(example, tries) ? :failed : :passed)
-        tries.later.each { |try| test_run.record_retry(id, try.status, try.duration_ms) }
+      # The first run of the example named `name`: its first attempt, timed by
+      # the engine up to the second try where a retry plugin made one, then
+      # each try after it, handed to the session once the first reached flaky
+      # detection. What the first attempt was is kept for its span.
+      def run_first(example, name, test_run, detector)
+        detector&.attempt_started(name)
+        tries = run_tries(example) { detector&.attempt_stopped(name) }
+        detector&.attempt_ended(name, first_failed?(example, tries) ? :failed : :passed)
+        tries.later.each { |try| test_run.record_retry(name, try.status, try.duration_ms) }
         example.metadata[:mergify_first_attempt] = { try: tries.first, ended_at: tries.first_ended_at } if tries.first
         tries
       end
@@ -252,13 +218,13 @@ module Mergify
       # `run_example`): answers the first failure, the reruns' included.
       # Each rerun is one try: a retry plugin's tries would hide its failure
       # behind the one that passed.
-      def rerun(example, detector, first_failure)
+      def rerun(example, name, detector, first_failure)
         without_retries(example) do
           until example.metadata[:is_last_rerun]
-            example.metadata[:is_last_rerun] = detector.last_rerun_for_test?(example.id)
+            example.metadata[:is_last_rerun] = detector.last_rerun_for_test?(name)
             reset_for_rerun(example)
 
-            run_attempt(example, detector)
+            run_attempt(example, name, detector)
             first_failure ||= example.exception
           end
         end
@@ -295,12 +261,12 @@ module Mergify
 
       # Runs what the around hook wraps -- the before and after hooks included
       # -- timed by the session, and answers its outcome.
-      def run_attempt(example, detector)
-        detector.attempt_started(example.id)
+      def run_attempt(example, name, detector)
+        detector.attempt_started(name)
         example.run
         failed = example.exception || example.metadata.delete(:mergify_quarantined_failure)
         status = failed ? :failed : :passed
-        detector.attempt_ended(example.id, status)
+        detector.attempt_ended(name, status)
         status
       end
 

data/lib/mergify/rspec/failure_first.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'set'
-require_relative 'native'
+require 'mergify/ci/core'
 
 module Mergify
   module RSpec
@@ -35,7 +35,7 @@ module Mergify
     # every example and group not started yet is left out, and the run exits 1.
     #
     # What to put first, when to stop, and the terminal block's words are the
-    # session's (`Native::Session#fail_first`), shared with every plugin: this
+    # session's (`Mergify::CI::Core::Native::Session#fail_first`), shared with every plugin: this
     # class reorders and quits.
     class FailureFirst
       class << self
@@ -57,8 +57,8 @@ module Mergify
 
         # Put first the examples the session puts first, and stop the run when
         # it says.
-        def apply(fail_first, examples, reporter:)
-          self.current = new(fail_first, examples)
+        def apply(fail_first, examples, names, reporter:)
+          self.current = new(fail_first, examples, names)
           current.reorder(top_level) if top_level
           reporter.register_listener(current, :example_finished)
           current
@@ -96,10 +96,11 @@ module Mergify
         end
       end
 
-      # An example's id is also the name Mergify knows it by.
-      def initialize(fail_first, examples)
+      # Each example goes by its id, which RSpec orders and reports it by,
+      # and is put first by the name Mergify knows it by (`names`).
+      def initialize(fail_first, examples, names)
         @fail_first = fail_first
-        @first_ids = fail_first.put_first(examples.map { |example| [example.id, example.id] }).to_set
+        @first_ids = fail_first.put_first(examples.map { |example| [example.id, names.of(example)] }).to_set
         @first_groups = groups_holding(examples.select { |example| @first_ids.include?(example.id) })
       end
 

data/lib/mergify/rspec/formatter.rb

@@ -3,7 +3,7 @@
 require 'rspec/core/formatters/base_formatter'
 require_relative 'configuration'
 
-require 'mergify/rspec/native'
+require 'mergify/ci/core'
 
 module Mergify
   module RSpec
@@ -34,8 +34,9 @@ module Mergify
 
         example = notification.example
         result = example.execution_result
-        @test_run.record_verdict(example.id, verdict_status(example), result.run_time)
-        recorded = @test_run.record_quarantine(example.id, real_outcome(example))
+        names = @test_run.names
+        @test_run.record_verdict(names.of(example), verdict_status(example), result.run_time)
+        recorded = @test_run.record_quarantine(names.keys(example), real_outcome(example))
         @has_error = true if result.status == :failed
         @test_run.record_case(case_of(example, recorded))
       end
@@ -120,7 +121,7 @@ module Mergify
       def case_of(example, recorded)
         first = first_attempt(example, recorded['absorbed'])
         {
-          'name' => example.id,
+          'name' => @test_run.names.of(example),
           'file' => example.metadata[:file_path].delete_prefix('./'),
           'function' => example.description,
           'start_unix_nano' => unix_nano(example.execution_result.started_at),
@@ -201,7 +202,7 @@ module Mergify
         return ['Mergify Test Engine is not configured.'] unless @test_run
         # A missing token or repository is the session's to say, with the
         # trace it could not upload.
-        return [] if Mergify::RSpec::Native.available?
+        return [] if Mergify::CI::Core::Native.available?
 
         [native_warning]
       end
@@ -211,7 +212,7 @@ module Mergify
       # git remote that is fine. Say what actually happened instead.
       def native_warning
         'WARNING: the Mergify native extension could not be loaded, so this run reports nothing: ' \
-          "#{Mergify::RSpec::Native.load_error&.message}"
+          "#{Mergify::CI::Core::Native.load_error&.message}"
       end
 
       # `text` in the colour of `severity` when RSpec colours its output, as

data/lib/mergify/rspec/names.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'mergify/ci/core'
+
+module Mergify
+  module RSpec
+    # The name Mergify knows each example by, which the gem hands the session
+    # wherever it speaks of one: the example's span and its verdict, the
+    # quarantine, flaky detection and Fail First.
+    #
+    # An example is named as minitest-mergify names a spec test, by
+    # `CI::Core::TestNames`: `<file> > <groups> > <description>`. The file is
+    # the one RSpec reruns the example from, so an example a shared group
+    # gives a spec is that spec's, relative to the directory the run started
+    # in. Nothing in it counts examples: RSpec's own id,
+    # `./spec/x_spec.rb[1:2]`, numbers an example by its place in its group,
+    # so adding one renamed every one after it, which then took the
+    # quarantine entry and the history of the one before. An example written
+    # without a description is titled by its block's code: RSpec writes it
+    # one from its matcher only once it ran, long after the session asked
+    # about it. A name its file repeats is followed by the example's place
+    # (`[1:2]`), so those examples stay apart.
+    #
+    # An example has two former names, which Mergify's lists may still hold
+    # it under: its id, which every earlier release named it by, and the
+    # name a JUnit upload gave it, for a suite that reported through
+    # rspec_junit_formatter and `mergify ci junit-process` before.
+    class Names
+      # `root` is the directory the run started in.
+      def initialize(root)
+        @root = root
+      end
+
+      def of(example)
+        name_all unless example.metadata.key?(:mergify_name)
+        example.metadata.fetch(:mergify_name)
+      end
+
+      # The names the example had before, which Mergify's lists may still
+      # hold it under.
+      def formers(example)
+        [example.id, junit_name(example)].compact
+      end
+
+      # Every name Mergify's lists may hold the example under, which the
+      # quarantine is asked with.
+      def keys(example)
+        [of(example), *formers(example)]
+      end
+
+      private
+
+      # Name every example RSpec loaded, each in its metadata: whether a name
+      # needs the example's place depends on the others of its file.
+      def name_all
+        names = unplaced_names
+        repeated = names.values.compact.tally.select { |_, count| count > 1 }.keys.to_set
+        names.each do |example, name|
+          example.metadata[:mergify_name] = name.nil? || repeated.include?(name) ? placed(example) : name
+        end
+      end
+
+      # Every example RSpec loaded, by its name without its place: nil for
+      # one that has no title.
+      def unplaced_names
+        examples = ::RSpec.world.example_groups.flat_map(&:descendants).flat_map(&:examples)
+        examples.to_h do |example|
+          title = title(example)
+          [example, title && spec_name(example, title)]
+        end
+      end
+
+      # Its name with its place after its title, as RSpec writes it: `[1:2]`.
+      def placed(example)
+        spec_name(example, [title(example), "[#{example.metadata[:scoped_id]}]"].compact.join(' '))
+      end
+
+      # Its description, or the code of its block when it was written without
+      # one; nil when there is none to read.
+      def title(example)
+        description = example.metadata[:description].to_s
+        return description unless description.empty?
+
+        block = example.metadata[:block]
+        CI::Core::TestNames.block_text(block) if block
+      end
+
+      # The name `mergify ci junit-process` gave the example from
+      # rspec_junit_formatter's report, `<class name>.<name>`: the class name
+      # the file of its outermost group, without its extension and with `/`
+      # as `.`, and the name its full description. Nil for an example written
+      # without a description that has not run yet: RSpec writes it one only
+      # once it ran.
+      def junit_name(example)
+        return if example.metadata[:description].to_s.empty?
+
+        # The formatter cuts the file's name at its first dot.
+        directory, name = File.split(example.example_group.parent_groups.last.metadata[:file_path])
+        classname = "#{directory}/#{name.sub(/\..*/, '')}".tr('/', '.').gsub(/\A\.+|\.+\z/, '')
+        "#{classname}.#{example.full_description}"
+      end
+
+      def spec_name(example, title)
+        groups = example.example_group.parent_groups.reverse.map(&:description)
+        CI::Core::TestNames.spec_name(example.metadata[:rerun_file_path], groups, title, @root)
+      end
+    end
+  end
+end

data/lib/mergify/rspec/quarantine.rb

@@ -16,15 +16,18 @@ module Mergify
         @list = list
       end
 
-      def include?(example_id)
-        @list.include?([example_id])
+      # Whether the list holds an example under any of `keys`, its names (see
+      # `Names#keys`).
+      def include?(keys)
+        @list.include?(keys)
       end
 
-      # Account for an example that ended with `outcome` (`'passed'`,
-      # `'failed'` or `'skipped'`, before the quarantine turned a failure into
-      # `pending`), as `{ 'quarantined' => bool, 'absorbed' => bool }`.
-      def record(example_id, outcome)
-        @list.record([example_id], outcome)
+      # Account for an example known by `keys` that ended with `outcome`
+      # (`'passed'`, `'failed'` or `'skipped'`, before the quarantine turned a
+      # failure into `pending`), as `{ 'quarantined' => bool, 'absorbed' =>
+      # bool }`.
+      def record(keys, outcome)
+        @list.record(keys, outcome)
       end
     end
   end

data/lib/mergify/rspec/test_run.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require_relative 'utils'
-require_relative 'native'
+require 'mergify/ci/core'
 require_relative 'flaky_detection'
+require_relative 'names'
 require 'json'
 require 'rspec/core/version'
 require 'set'
@@ -13,12 +14,10 @@ module Mergify
     # run's examples for its trace, and coordinates flaky detection,
     # quarantine and test selection.
     class TestRun
-      # What RSpec is, as the session takes it: its documentation page, where
-      # a run Test Selection refused is sent to read about
-      # MERGIFY_TEST_JOB_NAME; what it calls a test; what it can do about
-      # Fail First and reruns; and RSpec itself, which the trace names.
+      # What RSpec is, as the session takes it: what it calls a test; what it
+      # can do about Fail First and reruns; and RSpec itself, which the trace
+      # names.
       FRAMEWORK = {
-        docs_url: 'https://docs.mergify.com/test-engine/test-frameworks/rspec/',
         test_noun: 'example',
         # RSpec runs examples, in one process that can wait for every one put
         # first.
@@ -31,7 +30,7 @@ module Mergify
 
       attr_reader :session, :repo_name, :test_run_id,
                   :flaky_detector, :quarantined_tests,
-                  :captured_session_verdict
+                  :captured_session_verdict, :names
 
       # `doubles` has the session play Mergify in memory, answering and keeping
       # what it would send (the session's test doubles, by port, as a Hash:
@@ -44,16 +43,18 @@ module Mergify
         # What this process reads once: the CI context, the trace a caller
         # handed down, and the run's id; and the deprecated names the run
         # sets, which the summary names.
-        @session = Native::Session.start(Mergify::RSpec::VERSION, output, doubles, enabled?, **FRAMEWORK,
-                                         deprecated_variables: Utils.deprecated_env_names_in_use)
+        @session = Mergify::CI::Core::Native::Session.start(
+          Mergify::RSpec::VERSION, output, doubles, enabled?, client: 'rspec-mergify', **FRAMEWORK,
+                                                              deprecated_variables: Utils.deprecated_env_names_in_use
+        )
         @repo_name = @session.repository_name
         @test_run_id = @session.run_id
         @reruns = nil
         @flaky_detector = nil
         @quarantined_tests = nil
-        @decision = nil
         @captured_session_verdict = nil
         @examples_to_run = nil
+        @names = Names.new(Dir.pwd)
 
         set_up if reports?
       end
@@ -65,9 +66,10 @@ module Mergify
         @session.reports?
       end
 
-      # Hand the session what this run is about to execute, and answer what
-      # it executes of it, as the session decided: a Hash with `outcome`,
-      # `keep` and `refusal` (see `Native::Session#select`).
+      # Hand the session what this run is about to execute, and answer how it
+      # executes it, as the session decided: a Hash whose `outcome` is `full`
+      # or `failure_first` (see `Mergify::CI::Core::Native::Session#select`).
+      # Every example runs.
       #
       # Called once RSpec has loaded the spec files and applied every filter
       # of its own -- file and line arguments, `--tag`, `-e`,
@@ -77,13 +79,11 @@ module Mergify
       # own identity: the engine matches each against the previous attempt of
       # the same slice. It travels on the verdict and the trace of a run that
       # asked for the selection.
-      def select(example_ids)
+      def select(names)
         return unless reports?
 
-        @decision = @session.select(example_ids)
-        keep = @decision['keep']&.to_set
-        @examples_to_run = keep ? example_ids.count { |id| keep.include?(id) } : example_ids.size
-        @decision
+        @examples_to_run = names.size
+        @session.select(names)
       end
 
       # The run's Fail First, which the session hands out when Mergify
@@ -92,10 +92,10 @@ module Mergify
         @session.fail_first
       end
 
-      # Record an example's final status, as RSpec reported it, for the
-      # session's verdict.
-      def record_verdict(example_id, status, run_time)
-        @session.record_test(example_id, status, run_time.to_f)
+      # Record the final status of the example named `name`, as RSpec
+      # reported it, for the session's verdict.
+      def record_verdict(name, status, run_time)
+        @session.record_test(name, status, run_time.to_f)
       end
 
       # Write what this session concluded to Mergify, before the spans go.
@@ -117,19 +117,19 @@ module Mergify
       end
 
       # Hand the session an example once it finished, as the formatter says
-      # it (see `Native::Session#record_case`): its span joins the run's
+      # it (see `Mergify::CI::Core::Native::Session#record_case`): its span joins the run's
       # trace.
       def record_case(example)
         @session.record_case(example)
       end
 
-      # A retry plugin (rspec-retry) tried the example again after its first
-      # attempt, which ended with `status` (`'passed'` or `'failed'`) after
-      # `duration_ms`: the session counts it on the example's span, and as one
-      # of its runs where flaky detection runs, never against its budget or
-      # its execution cap.
-      def record_retry(example_id, status, duration_ms)
-        @session.record_retry(example_id, status, duration_ms)
+      # A retry plugin (rspec-retry) tried the example named `name` again
+      # after its first attempt, which ended with `status` (`'passed'` or
+      # `'failed'`) after `duration_ms`: the session counts it on the
+      # example's span, and as one of its runs where flaky detection runs,
+      # never against its budget or its execution cap.
+      def record_retry(name, status, duration_ms)
+        @session.record_retry(name, status, duration_ms)
       end
 
       # Have the session send the run's trace, once, at the end: the examples
@@ -150,20 +150,23 @@ module Mergify
         @session.summary(Utils.parallel_worker?)
       end
 
-      # Prepare flaky detection for the examples this run is about to run.
-      # Which of them it reruns, and whether it runs at all, are the
-      # session's.
-      def prepare_reruns(example_ids)
-        @reruns = @session.prepare_reruns(example_ids)
+      # Prepare flaky detection for the examples this run is about to run, by
+      # their names, each one Mergify's lists may still hold under its former
+      # names (`former_names`, a list by name). Which of them it reruns, and whether
+      # it runs at all, are the session's.
+      def prepare_reruns(names, former_names)
+        @session.state_former_names(former_names)
+        @reruns = @session.prepare_reruns(names)
         detection = @reruns&.detection
         @flaky_detector = detection && FlakyDetector.new(@reruns, detection)
       end
 
-      # Account for an example's real outcome against the quarantine list.
-      def record_quarantine(example_id, outcome)
+      # Account for the real outcome of the example known by `keys` against
+      # the quarantine list.
+      def record_quarantine(keys, outcome)
         return { 'quarantined' => false, 'absorbed' => false } unless @quarantined_tests
 
-        @quarantined_tests.record(example_id, outcome)
+        @quarantined_tests.record(keys, outcome)
       end
 
       private
@@ -193,7 +196,7 @@ module Mergify
       # be on whatever its value, so that `false` silently stopped the upload;
       # both names now take a boolean.
       def debug_mode?
-        Utils.env_truthy?(Utils.renamed_env(Utils::CI_DEBUG_ENV))
+        Mergify::CI::Core::Utils.env_truthy?(Utils.renamed_env(Utils::CI_DEBUG_ENV))
       end
 
       # Where the session sends the verdict and the trace: shown in debug mode,
@@ -205,7 +208,7 @@ module Mergify
       # The gem's enable switch, under every name it has had: the run then
       # reports outside CI too.
       def enabled?
-        Utils.env_truthy?(Utils.renamed_env(Utils::CI_ENABLE_ENV))
+        Mergify::CI::Core::Utils.env_truthy?(Utils.renamed_env(Utils::CI_ENABLE_ENV))
       end
     end
   end

data/lib/mergify/rspec/utils.rb

@@ -6,18 +6,16 @@ module Mergify
     #
     # CI detection used to live here -- the provider table, the git shelling
     # out, the per-provider environment mappings. It is the Rust core's now, via
-    # the extension in Mergify::RSpec::Native, so that every Mergify test client
-    # detects identically. What is left is what is genuinely Ruby's: parsing a
-    # repository name the API needs split, and reading the plugin's own
-    # switches.
+    # the extension in Mergify::CI::Core::Native, so that every Mergify test
+    # client detects identically. What is left is what is genuinely Ruby's:
+    # parsing a repository name the API needs split, and reading the plugin's
+    # own switches.
     module Utils
       module_function
 
       # Raised when a repository full name (owner/repo) is malformed.
       class InvalidRepositoryFullNameError < StandardError; end
 
-      TRUTHY_STRINGS = %w[y yes t true on 1].freeze
-
       CI_ENABLE_ENV = 'MERGIFY_CI_ENABLE'
       CI_DEBUG_ENV = 'MERGIFY_CI_DEBUG'
 
@@ -29,11 +27,6 @@ module Mergify
         CI_DEBUG_ENV => 'RSPEC_MERGIFY_DEBUG'
       }.freeze
 
-      # Returns true when the named environment variable holds a truthy value.
-      def env_truthy?(key)
-        TRUTHY_STRINGS.include?(ENV.fetch(key, '').downcase)
-      end
-
       # The variable to read for a setting in DEPRECATED_ENV_NAMES: its new
       # name once that is set to something, its deprecated one until then.
       def renamed_env(name)

data/lib/mergify/rspec/version.rb

@@ -8,6 +8,6 @@ module Mergify
     # which resolved against whatever repository happened to be the working
     # directory at load time -- the monorepo's namespaced tags here, the user's
     # own tags once the gem was installed.
-    VERSION = '2026.10.6'
+    VERSION = '2026.10.8'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-mergify
 version: !ruby/object:Gem::Version
-  version: 2026.10.6
+  version: 2026.10.8
 platform: ruby
 authors:
 - Mergify
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: mergify-ci-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2026.10.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2026.10.8
 description: 'RSpec integration for Mergify Test Engine: OpenTelemetry tracing, flaky
   test detection, and test quarantine.'
 email:
@@ -40,7 +54,7 @@ files:
 - lib/mergify/rspec/failure_first.rb
 - lib/mergify/rspec/flaky_detection.rb
 - lib/mergify/rspec/formatter.rb
-- lib/mergify/rspec/native.rb
+- lib/mergify/rspec/names.rb
 - lib/mergify/rspec/quarantine.rb
 - lib/mergify/rspec/test_run.rb
 - lib/mergify/rspec/tries.rb

data/lib/mergify/rspec/native.rb

@@ -1,130 +0,0 @@
-# frozen_string_literal: true
-
-module Mergify
-  module RSpec
-    # The Rust extension over mergify-ci-session: the session shared with the
-    # pytest and TypeScript clients.
-    #
-    # Loading is best-effort by design. A precompiled gem carries one extension
-    # per Ruby under `<ruby>/`, the source gem compiles one alongside this file,
-    # and a platform we publish neither for gets neither. Detection is one input
-    # to telemetry, not the point of the gem, so an absent extension degrades
-    # what we can report rather than breaking the suite under test -- the same
-    # fail-open posture the napi binding takes when a platform has no prebuilt
-    # binary. `load_error` keeps the reason, for callers that want to say so.
-    module Native
-      class << self
-        # The LoadError that prevented the extension loading, or nil.
-        attr_accessor :load_error
-
-        def available?
-          load_error.nil?
-        end
-
-        # Which of the two failed requires actually explains the absence.
-        #
-        # A precompiled gem ships lib/mergify/rspec/<ruby>/mergify_ci.<dlext>,
-        # so when one is packed for this Ruby that require is the real attempt:
-        # it fails with something like "version `GLIBC_2.29' not found", and the
-        # fallback that follows only ever adds "cannot load such file", which
-        # sends the reader looking for the wrong thing. With no extension for
-        # this Ruby -- the source gem, or a platform we publish no gem for --
-        # it is the other way round.
-        # Require a file next to this one, returning the LoadError instead of
-        # raising it. Two attempts read better as values than as nested rescues.
-        def attempt_require(path)
-          require_relative path
-          nil
-        rescue LoadError => e
-          e
-        end
-
-        def load_failure_reason(versioned, fallback)
-          packed = Dir.glob(File.join(__dir__, RUBY_VERSION.to_f.to_s, 'mergify_ci.*')).any?
-          packed ? versioned : fallback
-        end
-      end
-    end
-  end
-end
-
-# Precompiled gems ship lib/mergify/rspec/<ruby>/mergify_ci.<dlext>; the source
-# gem and any local `rake compile` put one beside this file instead.
-versioned_error = Mergify::RSpec::Native.attempt_require("#{RUBY_VERSION.to_f}/mergify_ci")
-fallback_error = versioned_error && Mergify::RSpec::Native.attempt_require('mergify_ci')
-
-if fallback_error
-  Mergify::RSpec::Native.load_error =
-    Mergify::RSpec::Native.load_failure_reason(versioned_error, fallback_error)
-end
-
-unless Mergify::RSpec::Native.available?
-  # Stand in for the extension so callers can just ask, and get the same answer
-  # they would get from a machine that is not in CI. Branching on availability
-  # at every call site would only spread the same nil back through the caller.
-  module Mergify
-    module RSpec
-      module Native
-        # A session that detects nothing, as on a machine that is not in CI.
-        class Session
-          def self.start(*)
-            new
-          end
-
-          # Nothing detected, so nothing to report to.
-          def reports?
-            false
-          end
-
-          def repository_name
-            nil
-          end
-
-          # Nothing detected: no run to name.
-          def run_id
-            nil
-          end
-
-          # Nothing to send a verdict with: it neither folds nor reports.
-          def record_test(_example_id, _status, _run_time); end
-
-          # Nothing to ask with: every example runs.
-          def select(_example_ids)
-            { 'outcome' => 'full', 'keep' => nil, 'refusal' => nil }
-          end
-
-          def executed_count
-            0
-          end
-
-          def report_verdict(_failed_outside_examples); end
-
-          def captured_verdict
-            nil
-          end
-
-          # Nothing to send a trace with either.
-          def record_case(_example); end
-
-          def record_retry(_example_id, _status, _duration_ms); end
-
-          def report_trace(_failed); end
-
-          # Nothing reported: nothing to say.
-          def summary(_partial)
-            []
-          end
-
-          def captured_trace
-            nil
-          end
-
-          # Nothing to rerun with.
-          def prepare_reruns(_example_ids)
-            nil
-          end
-        end
-      end
-    end
-  end
-end