turbo_tests2 3.2.13 → 3.2.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 966cd2f7569701b0c3930e26c6f1e447d8c6a61ecab97bcdf93a533633f4fd89
-  data.tar.gz: caa5ff5ead62c3efe9cf9eb994700dd1b7a06c54e3c54b5359e292ec3c9ab7ee
+  metadata.gz: b455a333f0fe9a3521173ff0e73b309b74baa6b37da905f5fcfa1a79a5eb075b
+  data.tar.gz: 8a2f7d15910049b3b8366fd1ed6e604581a6c7444a6e95babdcb2f344e73b054
 SHA512:
-  metadata.gz: 1608b69b29afc0a8af439b49615eea17e57aa8cab8a06e7724295376d6de0f194d2d9e0bf3f18b0d452193ab29cb652f21dc353de14c054afb0c0942fb016cee
-  data.tar.gz: fbc19b6c03e71b4274fd159f610e05a5c47f21327439af54bee05ce5f4a8d89d8dfb5728f246377ce2e4ac45ca4314013287f621233ebd7b74e20c578319cf4e
+  metadata.gz: 3cee9299d9a75a189a763621873df30959b68999972212f05f4ea81ba04200c66d9cbb56e2cc402947b58689881b16cdbc25ac9579205c473c4f359a2cab72ca
+  data.tar.gz: 8ec3ac430a73305ae22bbc58c4ad9e82e0f04f41645853b8da4d50a24f868fe5a6611e5a222774a423df2db89e5176f4f69221ed32adcb85771fab482093b85b

data/CHANGELOG.md

@@ -30,6 +30,58 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.15] - 2026-10-13
+
+- TAG: [v3.2.15][3.2.15t]
+- COVERAGE: 96.67% -- 988/1022 lines in 11 files
+- BRANCH COVERAGE: 85.06% -- 262/308 branches in 11 files
+- 39.42% documented
+
+### Changed
+
+- [kc] kettle-jem/prepare: updated 13 project files:
+  - configuration (1)
+  - dependencies (12)
+- [kc] kettle-jem/template: updated 12 project files:
+  - code and tests (2)
+  - documentation (1)
+  - other (2)
+  - workflows (7)
+
+### Fixed
+
+- The “Runtime and Platform Support” table in the README listed TruffleRuby 22.3, 23.0 and TruffleRuby-head as covered by CI, and described `rspec-pending_for` spec exclusions for 22.3/23.0. No workflow runs those engines (CI covers TruffleRuby 23.1, 24.2, 25.0, 33.0 and current), `heads.yml` runs `ruby-head` and `jruby-head` only, and `rspec-pending_for` is neither a dependency nor referenced by any spec. The badge rows for 22.3/23.0 had already been removed by templating, leaving the prose table describing CI that no longer runs.
+
+- Watchdog on the worker message queue: if no worker message arrives within TURBO_TESTS2_WATCHDOG_SECONDS (default 900), remaining workers are killed, unfinished groups reported, and the run fails — instead of blocking forever when a worker dies without an exit message (the parallel-worker CI hang class on 4-core runners)
+
+## [3.2.14] - 2026-10-08
+
+- TAG: [v3.2.14][3.2.14t]
+- COVERAGE: 96.93% -- 947/977 lines in 11 files
+- BRANCH COVERAGE: 85.57% -- 255/298 branches in 11 files
+- 39.42% documented
+
+### Changed
+
+- [kc] kettle-jem/prepare: updated 6 project files:
+  - dependencies (6)
+
+- [kc] kettle-jem/template: updated 4 project files:
+  - code and tests (1)
+  - documentation (1)
+  - other (1)
+  - workflows (1)
+
+### Fixed
+
+- rspec_configured_files_to_run: normalize discovered spec paths against the root cwd instead of the nearest ancestor .rspec. In stacked monorepos (root .rspec aggregating gems/*/spec via --pattern, where each gem also has its own .rspec), the nearest-ancestor walk stripped aggregated specs to bare member-relative spec/... paths that do not exist at the root, crashing parallel_tests File.stat during group sizing and aborting the whole run. Regression introduced in 3.2.13.
+
+- Fix a teardown race that intermittently dropped a worker's results. The exit-watcher thread previously signaled process exit as soon as the child was reaped, before the stdout/stderr readers had drained the pipe. Under CI contention handle_messages could reach process_count exits and stop while that worker's rows were still queued behind the exit signal, so they were never reported. Symptom was a nested run reporting "1 example, 0 failures" instead of "4 examples, 0 failures, 3 pending", with which worker vanished varying run to run (spec/integration/multi_process_spec.rb failed at :46 on one run and :52-54 on the next). Readers are now drained to EOF before the watcher signals exit, and the exit/error messages are a deduped fallback for a reader force-stopped before EOF. Drain uses one shared monotonic deadline across both streams (READER_DRAIN_TIMEOUT) so a wedged pipe whose write end stays open cannot double teardown time or hang; force-stop still closes the pipe and kills the reader as before.
+
+- Fix spec discovery returning absolute paths on Windows, which crashed parallel_tests' File.stat during group sizing. rspec_configured_files_to_run made discovered paths relative to the cwd with a string prefix check. On Windows the cwd and the discovered files can name the same directory with two different spellings: Dir.pwd and ENV["TEMP"] report the 8.3 short name (C:/Users/RUNNER~1/AppData/Local/Temp) while Dir.glob, which RSpec uses to expand --pattern, reports the long name (C:/Users/runneradmin/AppData/Local/Temp). The prefix therefore never matched and the absolute temp path leaked through. File.realpath does not expand 8.3 short names, so canonicalizing first cannot reconcile the two spellings, and Pathname#relative_path_from returns nonsense such as "../../../../../runneradmin/...". The same class of mismatch arises from a symlinked ancestor on any platform, e.g. a Dir.pwd of /var/home/u/proj against a path spelled /home/u/proj/... Discovered paths are now made relative by walking up from the file and comparing each ancestor with File.identical?, which compares by filesystem identity (inode on Unix, file index on Windows) and so treats every spelling of one directory as equal. Extracted as TurboTests::Utils::Paths.relative_from/.within?.
+
+- [kc] license-eye-workflow-retry: The Apache SkyWalking Eyes workflow retries the license check once before failing. The pinned `apache/skywalking-eyes/dependency` action is a composite that builds license-eye from source on every run, and its own dependency cache is broken upstream: `dependency/action.yml` passes `cache-dependency-path: ${{ github.action_path }}/go.sum`, but `go.sum` lives at the action's repository root rather than in `dependency/` (404 versus 200). setup-go therefore logs "Restore cache failed: Some specified paths were not resolved", the module cache never restores, and each run re-downloads roughly 35 Go modules and re-runs `make`. Every run is consequently exposed to a transient `proxy.golang.org` error — one such run failed with `stream error: stream ID 133; INTERNAL_ERROR; received from peer` after eleven consecutive successes. The retry follows the existing `[Attempt 1]`/`[Attempt 2]` idiom used by the Ruby matrix workflows.
+
 ## [3.2.13] - 2026-10-01
 
 - TAG: [v3.2.13][3.2.13t]
@@ -690,7 +742,11 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.13...HEAD
+[Unreleased]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.15...HEAD
+[3.2.15]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.14...v3.2.15
+[3.2.15t]: https://github.com/galtzo-floss/turbo_tests2/releases/tag/v3.2.15
+[3.2.14]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.13...v3.2.14
+[3.2.14t]: https://github.com/galtzo-floss/turbo_tests2/releases/tag/v3.2.14
 [3.2.13]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.12...v3.2.13
 [3.2.13t]: https://github.com/galtzo-floss/turbo_tests2/releases/tag/v3.2.13
 [3.2.12]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.11...v3.2.12

data/README.md

@@ -48,18 +48,17 @@ work in an untested environment:
 | MRI head | Parallel support | Unsupported | Unsupported | CI is allowed to fail while Ruby is in development. |
 | JRuby 9.2-9.4 | Parallel support | Unsupported | Unsupported | Versioned JRuby workflows run on Linux. |
 | JRuby 10.0/current/head | Parallel support | Unsupported | Unsupported | Experimental/current and head jobs are non-blocking in CI. |
-| TruffleRuby 22.3 | Parallel support | Unsupported | Unsupported | Experimental. The CLI and multi-process spec groups are skipped because this release reports Ruby compatibility version 3.0. |
-| TruffleRuby 23.0 | Single-worker support | Unsupported | Unsupported | Experimental and end-of-life; CI caps workers at one. The CLI and multi-process spec groups are also skipped. |
 | TruffleRuby 23.1 | Parallel support | Unsupported | Unsupported | Experimental. |
 | TruffleRuby 24.2/25.0/33.0/current | Parallel support | Unsupported | Unsupported | Linux workflows run the suite with parallel workers. |
-| TruffleRuby head | Parallel support | Unsupported | Unsupported | CI is allowed to fail while TruffleRuby is in development. |
 
-The TruffleRuby 22.3/23.0 spec exclusions use `rspec-pending_for`'s Ruby
-compatibility-version matching (`3.0`), not TruffleRuby's release number. They
-exclude the complete CLI spec group and multi-process integration group; the
-remaining suite still runs in parallel on 22.3 and serially on 23.0. The
-Windows current-Ruby job also runs in parallel, but runtime-log recording is
-disabled there because Windows file locking is unreliable (see below).
+The Windows current-Ruby job runs in parallel, but runtime-log recording is
+disabled there because the runtime logger needs file locking that Windows does
+not provide reliably (`record_runtime = !Gem.win_platform?`); see below.
+
+TruffleRuby 22.3, 23.0 and TruffleRuby-head are not listed because no workflow
+covers them. `heads.yml` runs `ruby-head` and `jruby-head` only, and
+`dep-heads.yml` runs the released `truffleruby` engine against head-of-branch
+dependencies, which is not a head engine build.
 
 ### Why incremental output?
 
@@ -99,7 +98,7 @@ Finished in 2 minute 25.15 seconds (files took 0 seconds to load)
 | Tokens to Remember | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace] |
 |-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Works with JRuby | [![JRuby 9.2 Compat][💎jruby-9.2i]][🚎jruby-9.2-wf] [![JRuby 9.3 Compat][💎jruby-9.3i]][🚎jruby-9.3-wf] <br/> [![JRuby 9.4 Compat][💎jruby-9.4i]][🚎jruby-9.4-wf] [![JRuby 10.0 Compat][💎jruby-10.0i]][🚎jruby-10.0-wf] [![JRuby current Compat][💎jruby-c-i]][🚎10-j-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf]|
-| Works with Truffle Ruby | [![Truffle Ruby 22.3 Compat][💎truby-22.3i]][🚎truby-22.3-wf] [![Truffle Ruby 23.0 Compat][💎truby-23.0i]][🚎truby-23.0-wf] [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎truby-23.1-wf] <br/> [![Truffle Ruby 24.2 Compat][💎truby-24.2i]][🚎truby-24.2-wf] [![Truffle Ruby 25.0 Compat][💎truby-25.0i]][🚎truby-25.0-wf] [![Truffle Ruby 33.0 Compat][💎truby-33.0i]][🚎truby-33.0-wf] [![Truffle Ruby current Compat][💎truby-c-i]][🚎9-t-wf] [![Truffle Ruby HEAD Compat][💎truby-headi]][🚎3-hd-wf]|
+| Works with Truffle Ruby | [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎truby-23.1-wf] <br/> [![Truffle Ruby 24.2 Compat][💎truby-24.2i]][🚎truby-24.2-wf] [![Truffle Ruby 25.0 Compat][💎truby-25.0i]][🚎truby-25.0-wf] [![Truffle Ruby 33.0 Compat][💎truby-33.0i]][🚎truby-33.0-wf] [![Truffle Ruby current Compat][💎truby-c-i]][🚎9-t-wf]|
 | Works with MRI Ruby 4 | [![Ruby current Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf]|
 | Works with MRI Ruby 3 | [![Ruby 3.0 Compat][💎ruby-3.0i]][🚎ruby-3.0-wf] [![Ruby 3.1 Compat][💎ruby-3.1i]][🚎ruby-3.1-wf] [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎ruby-3.2-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎ruby-3.3-wf] [![Ruby 3.4 Compat][💎ruby-3.4i]][🚎ruby-3.4-wf]|
 | Works with MRI Ruby 2 | [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎ruby-2.4-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎ruby-2.5-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎ruby-2.6-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎ruby-2.7-wf]|
@@ -138,6 +137,23 @@ The _amazing_ test matrix is powered by the kettle-dev stack.
 
 </details>
 
+### Runtime and Platform Support
+
+Support tiers describe what this project's CI actually exercises, not what may
+work in an untested environment:
+
+- **Parallel support**: CI runs the test suite with multiple workers available.
+- **Unsupported**: the engine/platform combination is not covered by CI and is
+ not a project compatibility claim.
+
+| Ruby engine/version | Linux | macOS | Windows | Notes |
+|---------------------|-------|-------|---------|-------|
+| MRI 3.1-3.4 | Parallel support | Unsupported | Unsupported | Versioned Ruby workflows run on Linux. |
+| MRI current | Parallel support | Parallel support | Unsupported | Current Ruby workflow covers the declared OS platforms. |
+| MRI head | Parallel support | Unsupported | Unsupported | CI is allowed to fail while Ruby is in development. |
+| JRuby (all CI lanes) | Parallel support | Unsupported | Unsupported | Engine workflows run on Linux; macOS and Windows are not exercised by CI. |
+| TruffleRuby (all CI lanes) | Parallel support | Unsupported | Unsupported | Never shipped a Windows build (zero Windows assets across 66 releases scanned 2026-10-10); setup-ruby hard-fails ([source](https://github.com/ruby/setup-ruby/blob/master/README.md)) |
+
 ### Federated DVCS
 
 <details markdown="1">
@@ -368,6 +384,43 @@ count at the number of discovered test groups.
 Known coverage formatter chatter remains collapsed into the concise coverage
 summary.
 
+### Stall watchdog
+
+If the worker message queue goes silent — every worker alive but none
+producing example/group messages — a run can otherwise hang until the CI
+provider kills the job (GitHub Actions: 6 hours).
+
+`TURBO_TESTS2_WATCHDOG_SECONDS=N` (integer, `0` = disabled) bounds that
+silence. **Default is `0` (disabled) in 3.x.** In 4.0 the default becomes
+`900` and the kill behavior is always on.
+
+When the watchdog fires it kills the remaining worker processes, prints the
+unfinished groups and worker pids, and fails the run.
+
+Setting it:
+
+```bash
+TURBO_TESTS2_WATCHDOG_SECONDS=900 bundle exec turbo_tests2
+```
+
+Notes:
+
+- The clock measures **silence across all workers**, not per-test duration.
+  In parallel lanes any other worker finishing an example keeps the run
+  alive; only serial lanes (`TURBO_TESTS2_MAX_PROCESSES=1`) can trip on a
+  single long test. Raise the value there if you have legitimately long,
+  silent tests.
+- CI jobs that hang despite the watchdog will still hit the provider
+  limit; also set `timeout-minutes` on the CI job. Locally, an outer
+  supervisor (process watcher, container timeout) plays the same role.
+- When the watchdog is disabled (`0`), a 900s silence prints a one-time
+  deprecation notice describing the 4.0 default change and both options
+  (adopt the kill via `TURBO_TESTS2_WATCHDOG_SECONDS`, or explicitly opt out
+  with `0`). The notice is provider-neutral: it warns that with the
+  watchdog off, whatever outer process watcher exists — a CI job timeout,
+  a container orchestrator, or a local supervisor — is what will eventually
+  end a hung run.
+
 `turbo_tests2` supports custom formatter such as Fuubar, but you might need to require it:
 
 ```bash
@@ -734,8 +787,6 @@ Thanks for RTFM. ☺️
 [🚎jruby-9.3-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/jruby-9.3.yml
 [🚎jruby-9.4-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/jruby-9.4.yml
 [🚎jruby-10.0-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/jruby-10.0.yml
-[🚎truby-22.3-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/truffleruby-22.3.yml
-[🚎truby-23.0-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/truffleruby-23.0.yml
 [🚎truby-23.1-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/truffleruby-23.1.yml
 [🚎truby-24.2-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/truffleruby-24.2.yml
 [🚎truby-25.0-wf]: https://github.com/galtzo-floss/turbo_tests2/actions/workflows/truffleruby-25.0.yml
@@ -771,14 +822,11 @@ Thanks for RTFM. ☺️
 [💎ruby-3.4i]: https://img.shields.io/badge/Ruby-3.4-CC342D?style=for-the-badge&logo=ruby&logoColor=white
 [💎ruby-c-i]: https://img.shields.io/badge/Ruby-current-CC342D?style=for-the-badge&logo=ruby&logoColor=green
 [💎ruby-headi]: https://img.shields.io/badge/Ruby-HEAD-CC342D?style=for-the-badge&logo=ruby&logoColor=blue
-[💎truby-22.3i]: https://img.shields.io/badge/Truffle_Ruby-22.3-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
-[💎truby-23.0i]: https://img.shields.io/badge/Truffle_Ruby-23.0-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-23.1i]: https://img.shields.io/badge/Truffle_Ruby-23.1-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-24.2i]: https://img.shields.io/badge/Truffle_Ruby-24.2-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-25.0i]: https://img.shields.io/badge/Truffle_Ruby-25.0-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-33.0i]: https://img.shields.io/badge/Truffle_Ruby-33.0-34BCB1?style=for-the-badge&logo=ruby&logoColor=pink
 [💎truby-c-i]: https://img.shields.io/badge/Truffle_Ruby-current-34BCB1?style=for-the-badge&logo=ruby&logoColor=green
-[💎truby-headi]: https://img.shields.io/badge/Truffle_Ruby-HEAD-34BCB1?style=for-the-badge&logo=ruby&logoColor=blue
 [💎jruby-9.2i]: https://img.shields.io/badge/JRuby-9.2-FBE742?style=for-the-badge&logo=ruby&logoColor=red
 [💎jruby-9.3i]: https://img.shields.io/badge/JRuby-9.3-FBE742?style=for-the-badge&logo=ruby&logoColor=red
 [💎jruby-9.4i]: https://img.shields.io/badge/JRuby-9.4-FBE742?style=for-the-badge&logo=ruby&logoColor=red
@@ -811,7 +859,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.947-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-1.022-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/galtzo-floss/turbo_tests2/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/turbo_tests/runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "timeout"
 require "fileutils"
 require "parallel_tests/rspec/runner"
 require "rspec/core"
@@ -8,6 +9,7 @@ require "shellwords"
 require "tempfile"
 
 require_relative "../utils/hash_extension"
+require_relative "utils/paths"
 
 module TurboTests
   class Runner
@@ -15,6 +17,16 @@ module TurboTests
     DEFAULT_RUNTIME_LOG = "tmp/turbo_rspec_runtime.log"
     DEFAULT_WORKER_OUTPUT_MODE = :warnings
     WORKER_OUTPUT_MODES = %i[warnings stream buffered quiet].freeze
+    # Shared wall-clock budget, in seconds, for draining a worker's stdout and
+    # stderr readers after the child has exited. Normally the pipe EOFs in
+    # milliseconds, so this is not on the hot path; the bound exists only for a
+    # wedged pipe whose write end is still held open (e.g. by a grandchild),
+    # which can never EOF. Shared across both streams so teardown cannot take
+    # twice the budget.
+    READER_DRAIN_TIMEOUT = 1
+    # Short join used only after the pipe is force-closed, to give the reader a
+    # moment to notice EOF before it is killed.
+    FORCE_STOP_JOIN = 0.1
 
     class << self
       def create(count)
@@ -160,23 +172,26 @@ module TurboTests
       def rspec_configured_files_to_run
         configuration = RSpec::Core::Configuration.new
         RSpec::Core::ConfigurationOptions.new(["spec"]).configure(configuration)
+        # Normalize against the cwd that owns the RSpec configuration being
+        # read, NOT the nearest .rspec ancestor of each file. parallel_tests
+        # stats these paths and spawns workers from this cwd, so the returned
+        # paths must resolve from here. In a stacked monorepo the root .rspec
+        # aggregates per-gem specs (each gem may also have its own .rspec);
+        # walking to the nearest .rspec would strip those to bare
+        # member-relative "spec/..." paths that do not exist at the root,
+        # crashing File.stat during group sizing.
+        #
+        # Compare paths by filesystem identity (File.identical?) rather than by
+        # string. On the Windows CI runner Dir.pwd reports the 8.3 short name
+        # (C:/Users/RUNNER~1/...) while Dir.glob, which RSpec uses to expand
+        # --pattern, reports the long name (C:/Users/runneradmin/...). Both
+        # spellings name the same directory, but File.realpath does NOT expand
+        # 8.3 names, so neither a string prefix nor Pathname#relative_path_from
+        # can reconcile them. The same class of mismatch arises from a symlinked
+        # ancestor. See TurboTests::Utils::Paths.
+        root = File.expand_path(Dir.pwd)
         configuration.files_to_run.map do |path|
-          expanded_path = File.expand_path(path.to_s).tr("\\", "/")
-          root = rspec_root_for(expanded_path)
-          root_prefix = "#{root}/"
-          expanded_path.start_with?(root_prefix) ? expanded_path[root_prefix.length..-1] : expanded_path
-        end
-      end
-
-      def rspec_root_for(path)
-        root = File.dirname(path)
-        loop do
-          return root.tr("\\", "/") if File.file?(File.join(root, ".rspec"))
-
-          parent = File.dirname(root)
-          return File.expand_path(Dir.pwd).tr("\\", "/") if parent == root
-
-          root = parent
+          TurboTests::Utils::Paths.relative_from(File.expand_path(path.to_s, root), root)
         end
       end
 
@@ -234,6 +249,12 @@ module TurboTests
       @load_time = 0
       @load_count = 0
       @failure_count = 0
+      # Deprecation-period default: disabled. In 4.0 the kill behavior
+      # becomes the default (TURBO_TESTS2_WATCHDOG_SECONDS=900) and this
+      # warning is removed. See README "Stall watchdog".
+      @watchdog_seconds = Float(ENV.fetch("TURBO_TESTS2_WATCHDOG_SECONDS", "0"))
+      @watchdog_warned = false
+      @last_message_monotonic = nil
 
       # Supports runtime_log as a top level option,
       #   but also nested inside parallel_options
@@ -477,10 +498,21 @@ module TurboTests
             status = wait_thr.value
             @failed_worker_statuses.store(process_id, status) unless status.success?
             @messages << {type: "error", process_id: process_id} unless status.success?
-            @messages << {type: "exit", process_id: process_id}
           ensure
-            stop_reader_thread(stdout_thread, stdout)
-            stop_reader_thread(stderr_thread, stderr)
+            # Drain BOTH readers before signaling this process's exit. The
+            # stdout reader parses the pipe into @messages rows and pushes its
+            # own {type: "exit"} at EOF; the stderr copy thread only buffers
+            # text into @worker_output and queues nothing, but it is drained
+            # too so no buffered warning output is lost. Signaling exit here
+            # first let handle_messages reach process_count exits and break
+            # while this worker's stdout rows were still queued behind that
+            # exit, silently dropping them (intermittent example undercount
+            # and missing streamed output under CI contention). The exit below
+            # is a deduped fallback for a stdout reader that was force-stopped
+            # before reaching EOF, and being in ensure also prevents a hang if
+            # wait_thr.value raises.
+            drain_worker_readers(stdout_thread, stdout, stderr_thread, stderr)
+            @messages << {type: "exit", process_id: process_id}
             untrack_parallel_pid(wait_thr.pid, pid_file_path)
           end
         end
@@ -675,22 +707,126 @@ module TurboTests
       "#{kind} Coverage: #{match[3]} (#{match[1]} / #{match[2]})"
     end
 
-    def stop_reader_thread(thread, io)
-      return if thread.join(0.1)
+    def drain_worker_readers(stdout_thread, stdout, stderr_thread, stderr)
+      # One shared deadline across both streams so a wedged pipe cannot double
+      # teardown time or hang the watcher. stdout carries the worker's JSON
+      # rows; stderr only carries buffered text.
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + READER_DRAIN_TIMEOUT
+      stop_reader_thread(stdout_thread, stdout, deadline)
+      stop_reader_thread(stderr_thread, stderr, deadline)
+    end
+
+    def stop_reader_thread(thread, io, deadline)
+      # Let the reader reach EOF and queue any buffered worker rows BEFORE any
+      # force-stop. Closing the pipe while the child's output is still
+      # kernel-buffered would discard it and silently drop that worker's
+      # results (intermittent example undercount / missing streamed output).
+      # The shared deadline bounds teardown when a pipe can never EOF because
+      # its write end is still held open (e.g. by a grandchild).
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return if remaining.positive? && thread.join(remaining)
 
       close_io(io)
-      return if thread.join(0.1)
+      return if thread.join(FORCE_STOP_JOIN)
+
+      thread.kill.join(FORCE_STOP_JOIN)
+    end
+
+    # Blocks for the next worker message, enforcing a stall watchdog. A
+    # worker whose stdout reader and exit-ensuring thread both fail to
+    # deliver an exit message (process killed by the OOM killer, forked
+    # child wedged in a native call) used to leave handle_messages blocked
+    # on the queue forever — CI jobs hung for hours with no diagnostics.
+    # On a stall we kill the surviving worker pids, report which groups
+    # never finished, and fail the run instead.
+    def pop_message_with_watchdog
+      # 0 (the default) disables the watchdog: block indefinitely, exactly the
+      # pre-watchdog behavior.
+      return @messages.pop if @watchdog_seconds <= 0
+
+      loop do
+        timeout = [@watchdog_seconds - (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_message_monotonic), 1.0].max
+        begin
+          message = Timeout.timeout(timeout) { @messages.pop }
+          @last_message_monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return message
+        rescue Timeout::Error
+          stall_report = remaining_workers_report
+          warn("turbo_tests2: no worker messages for #{@watchdog_seconds}s; killing stalled workers and failing the run")
+          warn(stall_report)
+          kill_remaining_workers
+          @reporter.error_outside_of_examples(
+            "turbo_tests2: watchdog fired after #{@watchdog_seconds}s without worker messages; workers killed\n#{stall_report}"
+          )
+          @error = true
+          return {type: "exit", process_id: :watchdog}
+        end
+      end
+    end
+
+    def remaining_workers_report
+      pids = tracked_pids
+      live = []
+      pids.each do |pid|
+        begin
+          Process.kill(0, pid)
+          live << pid
+        rescue
+          nil
+        end
+      end
+      lines = ["Workers total: #{@num_processes}; tracked pids: #{pids.inspect}; live: #{live.inspect}"]
+      (@tests_in_groups || []).each_with_index do |group, idx|
+        lines << "group #{idx + 1}: #{Array(group).join(", ")}" unless group.nil?
+      end
+      lines.join("\n")
+    end
 
-      thread.kill
-      thread.join(0.1)
+    def tracked_pids
+      path = ParallelTests.pid_file_path
+      return [] unless path && File.file?(path)
+
+      File.read(path).lines.map { |l| l.strip.to_i }.reject(&:zero?)
+    rescue
+      []
+    end
+
+    def kill_remaining_workers
+      tracked_pids.each do |pid|
+        begin
+          Process.kill("KILL", pid)
+        rescue
+          nil
+        end
+      end
     end
 
     def handle_messages
       exited_process_ids = {}
       process_count = @tests_in_groups&.size || @num_processes
 
+      # Tests pre-seed @last_message_monotonic to simulate a stall; only
+      # initialize it here when unset.
+      @last_message_monotonic ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      warned_silence = false
       loop do
-        message = @messages.pop
+        message = pop_message_with_watchdog
+        unless warned_silence
+          silence = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_message_monotonic
+          if silence >= 900
+            warn(
+              "turbo_tests2: workers have been silent for #{silence.to_i}s. " \
+              "In turbo_tests2 4.0 (and now when TURBO_TESTS2_WATCHDOG_SECONDS is set) a stall this long kills the " \
+              "remaining workers and fails the run. To adopt the kill now set TURBO_TESTS2_WATCHDOG_SECONDS=900 (or " \
+              "another value). To keep waiting indefinitely set TURBO_TESTS2_WATCHDOG_SECONDS=0; be aware that an " \
+              "outer process watcher (a CI job timeout, a container orchestrator, or a local supervisor) will then " \
+              "be what eventually ends the run, usually without a useful stall report. A single long test only " \
+              "trips this in serial lanes (TURBO_TESTS2_MAX_PROCESSES=1); in parallel lanes other workers keep " \
+              "messages flowing."
+            )
+            warned_silence = true
+          end
+        end
         case message[:type]
         when "example_passed"
           example = FakeExample.from_obj(message[:example])

data/lib/turbo_tests/utils/paths.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module TurboTests
+  module Utils
+    # Makes discovered spec paths relative to the cwd that owns the RSpec
+    # configuration, in a way that survives the same directory being spelled
+    # two different ways.
+    #
+    # == Why string comparison of paths is not safe here
+    #
+    # A path string is a *name*, not an identity. One directory can have
+    # several valid names, and the two names can reach this module from
+    # different APIs within the same process.
+    #
+    # On the Windows CI runner (windows-latest, github/actions) this is not
+    # hypothetical. Measured from the runner itself:
+    #
+    #   Dir.pwd        => "C:/Users/RUNNER~1/AppData/Local/Temp/turbo-tests2-...-ujisy2"
+    #   ENV["TEMP"]    => "C:\\Users\\RUNNER~1\\AppData\\Local\\Temp"
+    #   Dir.tmpdir     => "C:/Users/RUNNER~1/AppData/Local/Temp"
+    #   Dir.glob result => "C:/Users/runneradmin/AppData/Local/Temp/turbo-tests2-...-ujisy2/gems/example/spec/example_spec.rb"
+    #
+    # `RUNNER~1` is an 8.3 short name; `runneradmin` is the long name of the
+    # same directory. `Dir.pwd` and the environment report the short form while
+    # `Dir.glob` — which RSpec uses to expand `--pattern` — reports the long
+    # form. Both are correct, and they are never equal as strings.
+    #
+    # In this codebase the mismatch has a second, platform-independent face:
+    # a symlinked ancestor. On Fedora, `/home/pboling` is a symlink to
+    # `/var/home/pboling`, so `Dir.pwd` can report one form while a path built
+    # from an ENV var or a stored fixture reports the other. That is what makes
+    # this bug reproducible in specs without a Windows runner.
+    #
+    # == Approaches that do NOT work, and why
+    #
+    # All four were tried on this branch and all failed. Recorded so nobody
+    # repeats the sequence.
+    #
+    # 1. String prefix, the original code:
+    #
+    #      root_prefix = "#{root}/"
+    #      expanded.start_with?(root_prefix)
+    #
+    #    Never matches when the two spellings differ, so the absolute temp path
+    #    leaks through. parallel_tests then calls File.stat on it during group
+    #    sizing. It also wrongly reports "project-other/spec" as inside
+    #    "project", which is why spec/utils/paths_spec.rb covers siblings.
+    #
+    # 2. Canonicalize with File.realpath, then compare:
+    #
+    #      File.realpath(path) == File.realpath(root) # conceptually
+    #
+    #    WRONG PREMISE: File.realpath does NOT expand 8.3 short names. Measured
+    #    on the runner, realpath of the short path returns the short path
+    #    unchanged:
+    #
+    #      root_realpath => "C:/Users/RUNNER~1/AppData/Local/Temp/turbo-tests2-..."
+    #
+    #    Canonicalization therefore cannot reconcile the two spellings at all.
+    #    (kettle-dev's Kettle::Dev::Paths.canonical documents realpath as
+    #    expanding 8.3 names; that comment is inaccurate. Worth correcting if
+    #    this module is ever extracted to a shared gem.)
+    #
+    #    realpath also resolves symlinks, which introduces a second failure
+    #    mode: root and file can legitimately traverse different symlink paths
+    #    to one directory, and canonicalizing only one side makes them diverge.
+    #
+    # 3. Component-wise comparison of the canonicalized parts (split on
+    #    File::SEPARATOR, compare element by element, case-insensitively on
+    #    Windows). Built on the same false premise as #2, so it fails
+    #    identically — `RUNNER~1` never equals `runneradmin` in any case
+    #    folding. It additionally depended on File::ALT_SEPARATOR, which
+    #    measured as "" (empty string, not nil) on that runner, making the
+    #    separator-normalizing `tr` a silent no-op. Do not trust ALT_SEPARATOR
+    #    to be present.
+    #
+    # 4. Pathname#relative_path_from, Ruby's own stdlib helper:
+    #
+    #      Pathname.new(file).relative_path_from(Pathname.new(root)).to_s
+    #
+    #    It is purely lexical. With differing spellings it walks all the way up
+    #    and back down, producing:
+    #
+    #      "../../../../../runneradmin/AppData/Local/Temp/.../example_spec.rb"
+    #
+    #    Note it does not raise, so a `rescue ArgumentError` guard cannot catch
+    #    it. The result is a plausible-looking but wrong relative path, which is
+    #    worse than the leak in #1 because it silently selects the wrong files.
+    #    The same nonsense appears on the symlink case:
+    #    "../../../../../../var/home/pboling/src/my/...".
+    #
+    # == The approach that works
+    #
+    # File.identical? asks the filesystem whether two names denote one object,
+    # by inode on Unix and by file index on Windows. It is spelling-agnostic,
+    # which is exactly the property needed. Measured on the runner:
+    #
+    #   File.identical?(root, root) => true
+    #   File.identical?(file, file) => true
+    #
+    # and a walk-up from the long-name file to the short-name root produced the
+    # correct "gems/example/spec/example_spec.rb", while the string-prefix and
+    # Pathname baselines both failed in the same run.
+    #
+    # So: ascend from the file, asking at each level "is this the root?", and
+    # re-join the basenames on the way back down. The relative path is built
+    # from the *file's* spelling, which is what the caller needs, since
+    # parallel_tests stats these paths and spawns workers from this cwd.
+    #
+    # == How this was finally diagnosed
+    #
+    # The failure only reproduced on the Windows CI runner, and its output was
+    # swallowed: these discovery specs run a subprocess via Open3.capture3 whose
+    # stderr is only surfaced when the status check fails, and the assertion
+    # that failed was the JSON comparison. Four blind fixes failed in a row.
+    #
+    # What resolved it was a temporary, Windows-guarded spec
+    # (`if: Gem.win_platform?`) that deliberately failed with the diagnostic
+    # JSON embedded in the expectation message, so the runner's real path forms
+    # printed into the CI log. Guarding it kept the other 22 checks green while
+    # one job reported the data. That spec is deleted; the findings it produced
+    # are this comment plus spec/utils/paths_spec.rb.
+    #
+    # Lesson: when a bug is environment-specific and the environment is not
+    # available locally, spend the iteration on instrumenting the real
+    # environment rather than on another hypothesized fix.
+    module Paths
+      module_function
+
+      # Returns the path of +file+ relative to +root+ when +file+ is +root+
+      # itself or lives inside it, compared by filesystem identity rather than
+      # by string.
+      #
+      # Returns the expanded +file+ unchanged when it is not inside +root+
+      # (there is nothing to strip) or when identity cannot be established,
+      # e.g. because one side does not exist. That matches the long-standing
+      # behavior of passing through paths outside the root untouched.
+      #
+      # @param file [String, Pathname] path to make relative; expanded against
+      #   the current directory when relative
+      # @param root [String, Pathname] directory to make +file+ relative to
+      # @return [String] relative path using File::SEPARATOR, "." when the two
+      #   name the same directory, or the expanded +file+ when it is not inside
+      #   +root+
+      def relative_from(file, root)
+        expanded_file = File.expand_path(file.to_s)
+        relative = relative_to_root(expanded_file, root)
+
+        relative || expanded_file
+      end
+
+      # Returns true when +file+ is +root+ itself or lives inside it, compared
+      # by filesystem identity.
+      #
+      # Unlike a string prefix test this does not treat a sibling directory
+      # that merely shares a prefix ("project-other") as being inside "project".
+      #
+      # @param file [String, Pathname, nil]
+      # @param root [String, Pathname, nil]
+      # @return [Boolean] false when either argument is nil or empty
+      def within?(file, root)
+        return false if blank?(file) || blank?(root)
+
+        relative_to_root(File.expand_path(file.to_s), root).is_a?(String)
+      end
+
+      # The path of +expanded_file+ relative to +root+: "." when they name the
+      # same directory, or nil when +root+ is not an ancestor.
+      #
+      # Guarded by File.exist? on both sides because File.identical? raises
+      # ENOENT rather than returning false for a missing path, and because a
+      # path that does not exist has no filesystem identity to compare.
+      def relative_to_root(expanded_file, root)
+        expanded_root = File.expand_path(root.to_s)
+        return nil unless File.exist?(expanded_file) && File.exist?(expanded_root)
+
+        relative_parts(expanded_file, expanded_root)
+      end
+      private_class_method :relative_to_root
+
+      # Ascend until the two paths are identical by filesystem identity,
+      # re-joining basenames on the way back down.
+      #
+      # Recursion terminates on its own: File.dirname of the filesystem root
+      # returns itself ("C:/" or "/"), so the `parent == expanded_file` check
+      # ends every walk. No depth constant is needed. Depth is bounded by the
+      # path length, which is shallow for any real spec tree; the cost is one
+      # stat pair per level.
+      #
+      # @return [String, nil] relative path, "." for the same directory, or nil
+      #   when the root was never reached
+      def relative_parts(expanded_file, expanded_root)
+        return "." if identical?(expanded_file, expanded_root)
+
+        parent = File.dirname(expanded_file)
+        return nil if parent == expanded_file
+
+        append_basename(relative_parts(parent, expanded_root), File.basename(expanded_file))
+      end
+      private_class_method :relative_parts
+
+      # Prepend +basename+ to the tail produced by the level above. Propagates
+      # nil, so "root not found" survives the unwind instead of being rebuilt
+      # into a partial path.
+      def append_basename(tail, basename)
+        return nil unless tail
+
+        (tail == ".") ? basename : File.join(tail, basename)
+      end
+      private_class_method :append_basename
+
+      # Filesystem-identity comparison that tolerates a missing path, where
+      # File.identical? raises ENOENT. Falls back to string equality, which is
+      # the correct answer when neither side is a symlink or an 8.3 short name.
+      #
+      # Rescues SystemCallError rather than Errno::ENOENT alone, because
+      # ENOTDIR, ELOOP and EACCES all mean "identity unknown" here, and the
+      # string fallback is the safest available answer in each case.
+      def identical?(left, right)
+        File.identical?(left, right)
+      rescue SystemCallError
+        left == right
+      end
+      private_class_method :identical?
+
+      # Treats nil and "" alike. Uses to_s so nil never reaches a nil-check
+      # that a linter would flag, and so a Pathname or other to_s-able object
+      # is accepted.
+      def blank?(value)
+        value.to_s.empty?
+      end
+      private_class_method :blank?
+    end
+  end
+end

data/lib/turbo_tests/version.rb

@@ -4,7 +4,7 @@ module TurboTests
   # Version namespace for this gem.
   module Version
     # Current gem version.
-    VERSION = "3.2.13"
+    VERSION = "3.2.15"
   end
   # Current gem version exposed at the traditional constant location.
   VERSION = Version::VERSION # Traditional Constant Location

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_tests2
 version: !ruby/object:Gem::Version
-  version: 3.2.13
+  version: 3.2.15
 platform: ruby
 authors:
 - Illia
@@ -111,7 +111,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.5
+        version: 3.1.11
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -121,7 +121,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.5
+        version: 3.1.11
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -219,7 +219,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.23
+        version: 2.0.24
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -229,7 +229,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.23
+        version: 2.0.24
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -273,7 +273,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.13
+        version: 2.0.15
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -283,7 +283,7 @@ dependencies:
         version: '2.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.13
+        version: 2.0.15
 description: "\U0001F680 turbo_tests2` is an RSpec parallel test runner built on `parallel_tests`.
   It uses `parallel_tests` for process counts, file grouping, and runtime balancing,
   then replaces interleaved worker output with incremental summarized RSpec reporting.
@@ -306,6 +306,7 @@ files:
 - lib/turbo_tests/reporter.rb
 - lib/turbo_tests/runner.rb
 - lib/turbo_tests/shim.rb
+- lib/turbo_tests/utils/paths.rb
 - lib/turbo_tests/version.rb
 - lib/turbo_tests2.rb
 - lib/turbo_tests2/rspec/shared_contexts/simplecov_spawn.rb
@@ -315,10 +316,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://turbo-tests2.galtzo.com
-  source_code_uri: https://github.com/galtzo-floss/turbo_tests2/tree/v3.2.13
-  changelog_uri: https://github.com/galtzo-floss/turbo_tests2/blob/v3.2.13/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/turbo_tests2/tree/v3.2.15
+  changelog_uri: https://github.com/galtzo-floss/turbo_tests2/blob/v3.2.15/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/turbo_tests2/issues
-  documentation_uri: https://www.rubydoc.info/gems/turbo_tests2/3.2.13
+  documentation_uri: https://www.rubydoc.info/gems/turbo_tests2/3.2.15
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/galtzo-floss/turbo_tests2/wiki
   news_uri: https://www.railsbling.com/tags/turbo_tests2