padded_cell 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d2b2f1c6d06b6cf4e72a67cfb6d511cc121fad2794d5fffc84bbf323c8431f1
-  data.tar.gz: '08aacbd7f382259c1eee0b45e3508c7dba4522be0c6d57ba4ca13b496ba70a1b'
+  metadata.gz: 8c460bc9c30d1aceca5e6e4dd764503b7871971c2da3c8aaa7e497581717f92f
+  data.tar.gz: f72d0d43ff6ba9fe4505bc2c1293fefc073c89c905b0ae8fa4f8fb27784d597d
 SHA512:
-  metadata.gz: d473da59b1f2de1ae4cee4d423c8361ffcf42060bd8b4fd264894a82c6d631cdddd8e8ee376716ae0d73db4ea4e3aefbf540fdbd42b20ed996ca024740448aba
-  data.tar.gz: 4d7a2de1bad5aaf24df760011df2a9728193586640bb7f7f14a9dcd66d38750082995692736bdfc0a4ccb951fb174384d600ac723414a39e0c479d98203f2515
+  metadata.gz: c72c3a035714f8c70cb2a93461cde0c447e2417f954af98e23dc689e3b375bda3bd1132527fe0110b2e964ac33c45999e975146d214f7e71230e96e2eb383818
+  data.tar.gz: fb6a39de58a92cf0abb8fc3bedfb8f8d72fa3fa14179508e27d416c259e77c73fda818daee6d06ea7f83f95b72432776c1a63a8ba0d692cbb82df73454e28371

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.0 (2026-11-08)
+
+- `PADDED_CELL_ASYLUM`: retries failures from the environment. N retries,
+  or `true`/`yes`/`on` for the default 2; `0`, `false`, `no` and `off` leave
+  it off. `--asylum` still wins.
+- `--coverage-map PATH` (or `PADDED_CELL_COVERAGE_MAP`): the lines each test
+  ran, as JSON lines (`{"id":…,"file":…,"line":…,"covers":{path => lines}}`),
+  for CI that reruns only the tests a diff touches. Turns on
+  `--coverage=lines,methods` when coverage is off; never changes the summed
+  report. Free with `--isolation test`; with `--isolation worker`, two
+  coverage copies per test.
+
 ## 0.3.0 (2026-11-08)
 
 - `--budget SECONDS`: a deadline for the whole run, loading included. Once

data/Cargo.lock

@@ -226,7 +226,7 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "padded_cell"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "ruby-prism",
  "supervisor-machines",
@@ -236,7 +236,7 @@ dependencies = [
 
 [[package]]
 name = "padded_cell_native"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "deadline-machines",
  "magnus",

data/README.md

@@ -72,6 +72,7 @@ $ padded_cell --timeout 30                 # kill and fail anything running 30s
 $ padded_cell --budget 600                 # the whole run gets 10 minutes; what's left out fails it
 $ padded_cell --fail-fast
 $ padded_cell --asylum                     # retry failures; report the flaky ones (see below)
+$ PADDED_CELL_ASYLUM=2 padded_cell         # same, from a CI runner's env
 $ padded_cell --list                       # what would run, without loading anything
 $ padded_cell --shard 2/4                  # CI: the second quarter of the classes
 $ padded_cell --junit tmp/junit.xml --json tmp/results.jsonl
@@ -271,6 +272,38 @@ The merge refuses files that differ between shards or from the checkout,
 and checks thresholds when every shard of the run is there. Lines that run
 while the suite loads count once per shard.
 
+### Coverage map
+
+Which lines each test ran, so CI can rerun only the tests touching a diff:
+
+```console
+$ padded_cell --coverage-map tmp/coverage_map.jsonl
+$ PADDED_CELL_COVERAGE_MAP=tmp/coverage_map.jsonl padded_cell   # same; the flag wins
+```
+
+One JSON object per test, in id order, written at the end of the run:
+
+```json
+{"id":"SignTest#test_zero","file":"test/calc_test.rb","line":28,"covers":{"lib/calc.rb":[[7,8],10,13]}}
+```
+
+`covers` holds the files the coverage report shows (filters apply, `test/`
+stays out), each with its line numbers ascending, `[first, last]` for a run
+of consecutive ones. Lines a test runs while loading a file count for it.
+
+Ruby's line coverage never sees a call to `def add(a, b) = a + b`: with
+`methods` measured, every method a test called adds its def line. Without
+`--coverage`, the map turns on `lines,methods`. With it, the map adds no
+criterion, so the report is byte for byte the same as without the map:
+include `methods`, or one-liners go unmapped.
+
+First attempts only, like the report. A test whose cell or worker died is
+left out: it was not measured, so a selector should run it anyway.
+
+A cell's measure is already its test's: free under `--isolation test`. With
+`--isolation worker`, Ruby copies the coverage of every loaded file twice per
+test (about 24 ms with 800 files loaded, more in a big Rails app).
+
 ### Cost
 
 Measuring is opt-in: Ruby's instrumentation slows tests down. On a Rails

data/ext/padded_cell_native/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "padded_cell"
-version = "0.3.0"
+version = "0.4.0"
 description = "Static Minitest discovery and test scheduling for the padded_cell gem"
 publish = false
 edition.workspace = true

data/ext/padded_cell_native/core/src/chart/source.rs

@@ -51,15 +51,24 @@ impl Source {
     /// The 1-based line and the 0-based byte column of `offset`.
     #[must_use]
     pub fn position(&self, offset: usize) -> (u32, u32) {
-        let line = self.ends.partition_point(|&end| end <= offset);
+        let line = self.line_index(offset);
         let number = |value: usize| u32::try_from(value).unwrap_or(u32::MAX);
-        (number(line.strict_add(1)), number(offset.strict_sub(self.line_start(offset))))
+        (number(line.strict_add(1)), number(offset.strict_sub(self.start_of(line))))
     }
 
     /// Where the line holding `offset` starts.
     #[must_use]
     pub fn line_start(&self, offset: usize) -> usize {
-        let line = self.ends.partition_point(|&end| end <= offset);
+        self.start_of(self.line_index(offset))
+    }
+
+    /// The 0-based line holding `offset`.
+    fn line_index(&self, offset: usize) -> usize {
+        self.ends.partition_point(|&end| end <= offset)
+    }
+
+    /// Where the 0-based `line` starts.
+    fn start_of(&self, line: usize) -> usize {
         line.checked_sub(1).map_or(0, |previous| self.ends[previous])
     }
 

data/ext/padded_cell_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "padded_cell_native"
-version = "0.3.0"
+version = "0.4.0"
 description = "Ruby bindings for the padded_cell crate"
 publish = false
 edition.workspace = true

data/lib/padded_cell/cell.rb

@@ -24,7 +24,7 @@ module PaddedCell
       pid = fork_cell(klass, name, seed, reader, writer, close, probe)
       writer.close
       delta, result = collect(pid, reader, klass, name, started, deadline) { limits.message(deadline) }
-      delta ? probe.absorb(delta) : probe&.lost
+      delta ? probe.absorb(delta, result) : probe&.lost
       result
     ensure
       reader&.close

data/lib/padded_cell/chart/accumulator.rb

@@ -13,11 +13,14 @@ module PaddedCell
       attr_reader :criteria
 
       # criteria: what Ruby's Coverage measures, :lines always among them
-      def initialize(criteria)
+      # map: each test's lines go on its result too (--coverage-map)
+      def initialize(criteria, map: false)
         @criteria = criteria
+        @map = map
         @root = File.realpath(Dir.pwd)
         @roots = [Dir.pwd, @root].uniq.map { "#{it}/" }
         @kept = {}
+        @names = {}
         @lost = 0
         @known = Set.new
       end
@@ -39,7 +42,16 @@ module PaddedCell
       # For a worker, right after its fork.
       def probe
         Probe.new(file: File.join(@frames, "#{Process.pid}.cov"), known: @known, keep: method(:keep?),
-                  methods: @criteria.include?(:methods), interval: Chart.config.interval)
+                  methods: @criteria.include?(:methods), interval: Chart.config.interval, map: @map)
+      end
+
+      # A measured file's name in the report, or nil for a file the report
+      # leaves out (filtered, outside the root, deleted).
+      def project_file(path)
+        @names.fetch(path) do
+          name = relative(path)
+          @names[path] = (name if name && !Chart.config.skipped?(path, name))
+        end
       end
 
       # A worker died: what it measured since its last flush is gone.
@@ -85,19 +97,25 @@ module PaddedCell
         end
       end
 
-      # Keys by real path relative to the root: a file required through a
-      # symlink and through its real path is one file. A file deleted during
-      # the run is not reported.
+      # Keys by real path relative to the root.
       def normalize(total)
         total.each_with_object({}) do |(path, entry), files|
-          relative = File.realpath(path).delete_prefix("#{@root}/")
-          next if relative.start_with?('/')
+          relative = relative(path)
+          next unless relative
 
           files[relative] ? Delta.merge!(files, { relative => entry }) : files[relative] = entry
-        rescue SystemCallError
-          next
         end
       end
+
+      # By real path: a file required through a symlink and through its real
+      # path is one file. nil outside the root, or for a file deleted during
+      # the run.
+      def relative(path)
+        relative = File.realpath(path).delete_prefix("#{@root}/")
+        relative unless relative.start_with?('/')
+      rescue SystemCallError
+        nil
+      end
     end
   end
 end

data/lib/padded_cell/chart/config.rb

@@ -65,6 +65,12 @@ module PaddedCell
       end
       alias filter skip
 
+      # Whether a filter leaves the file out (path absolute, name relative).
+      def skipped?(path, name)
+        file = SourceFile.new(path, name)
+        @filters.any? { it.call(file) }
+      end
+
       # Removes every filter, the defaults included.
       def clear_filters = @filters.clear
 

data/lib/padded_cell/chart/delta.rb

@@ -51,6 +51,19 @@ module PaddedCell
         total
       end
 
+      # {path => [line number, ...]}: the lines that ran, ascending, by file.
+      # A call to `def add(a, b) = a + b` runs no line Ruby sees: methods,
+      # when measured, add the first line of every method that ran.
+      def ran(delta)
+        delta.each_with_object({}) do |(path, entry), ran|
+          lines = entry[:lines]
+          indices = lines.is_a?(Hash) ? lines.keys : lines.each_index.select { lines[it]&.positive? }
+          numbers = indices.map { it + 1 }
+          entry[:methods]&.each { |(_, first), (_, hits)| numbers << first if hits.positive? }
+          ran[path] = numbers.uniq.sort unless numbers.empty?
+        end
+      end
+
       # Coverage's arrays are frozen.
       def dense(data)
         {

data/lib/padded_cell/chart/probe.rb

@@ -16,15 +16,22 @@ module PaddedCell
     # A flush copies the coverage of every file Ruby loaded, gems included: a
     # few milliseconds in a small app, a few hundred in a big Rails one. The
     # interval stretches to keep flushes under 1% of a worker's time.
+    #
+    # With the map on (--coverage-map), each test's result also carries the
+    # lines it ran, in its metadata under :covers. A cell's delta is already
+    # its test's; a worker running tests itself clears Coverage around each
+    # one, two more copies per test. What it clears goes into its measure, so
+    # the sum does not change.
     class Probe
       INTERVAL = 10.0
       BUDGET = 100
 
-      def initialize(file:, known:, keep:, methods:, interval: INTERVAL)
+      def initialize(file:, known:, keep:, methods:, interval: INTERVAL, map: false)
         @file = file
         @known = known
         @keep = keep
         @methods = methods
+        @map = map
         @interval = interval
         @wait = interval
         @pending = {}
@@ -40,8 +47,22 @@ module PaddedCell
       # The delta of a cell, at its end.
       def capture = Delta.capture(::Coverage.peek_result, @known, @keep)
 
-      # A cell's delta, in its worker.
-      def absorb(delta) = Delta.merge!(@pending, delta)
+      # A cell's delta, in its worker; with the map on, result gets the lines
+      # its test ran.
+      def absorb(delta, result = nil)
+        result.metadata[:covers] = Delta.ran(delta) if @map && result
+        Delta.merge!(@pending, delta)
+      end
+
+      # Runs a test in the worker (isolation :worker), which yields its result.
+      def measure
+        return yield unless @map
+
+        absorb(clear)
+        result = yield
+        absorb(clear, result)
+        result
+      end
 
       # A cell that died before reporting.
       def lost = @lost += 1
@@ -53,7 +74,7 @@ module PaddedCell
 
       def flush
         started = Minitest.clock_time
-        delta = Delta.merge!(Delta.capture(::Coverage.result(stop: false, clear: true), @known, @keep), @pending)
+        delta = Delta.merge!(clear, @pending)
         frame = Marshal.dump({ delta:, lost: @lost })
         File.open(@file, 'ab') { it.write([frame.bytesize].pack('N') + frame) }
         # Dense entries brought their structure to the runner: from now on,
@@ -65,6 +86,11 @@ module PaddedCell
         # 0: after every test, whatever it costs.
         @wait = @interval.zero? ? 0 : [@interval, (@flushed - started) * BUDGET].max
       end
+
+      private
+
+      # What ran since the last clear, taken out of Coverage.
+      def clear = Delta.capture(::Coverage.result(stop: false, clear: true), @known, @keep)
     end
   end
 end

data/lib/padded_cell/chart/source_files.rb

@@ -19,7 +19,7 @@ module PaddedCell
         loaded = loaded_features
         never, @unmeasured = tracked(files).partition { !loaded.include?(File.join(root, it)) }
         @rows = (files.map { |name, entry| row(name, entry) } + stubs(never))
-                .reject { |path, name| skipped?(path, name) }
+                .reject { |path, name| @config.skipped?(path, name) }
                 .sort_by { it[1] }
       end
 
@@ -72,11 +72,6 @@ module PaddedCell
         end
       end
 
-      def skipped?(path, name)
-        file = SourceFile.new(path, name)
-        @config.filters.any? { it.call(file) }
-      end
-
       # Required files, also under the root's real path.
       def loaded_features
         pwd = "#{Dir.pwd}/"

data/lib/padded_cell/cli.rb

@@ -22,7 +22,8 @@ module PaddedCell
     # Exit status: 0 passed, 1 failed, 2 usage or load error, 3 coverage below
     # a minimum, 130 interrupted.
     def start(argv, io: $stdout)
-      options = { io:, coverage: coverage_criteria(ENV.fetch('PADDED_CELL_COVERAGE', nil)), **report_paths }
+      options = { io:, coverage: coverage_criteria(ENV.fetch('PADDED_CELL_COVERAGE', nil)), **report_paths,
+                  **asylum_from_env }
       parser(options).parse!(argv)
       return merge(options) if options[:coverage_merge]
 
@@ -34,12 +35,22 @@ module PaddedCell
     end
 
     # Report paths a CI runner can set without touching the command line;
-    # --json and --junit still win.
+    # --json, --junit and --coverage-map still win.
     def report_paths
-      { json: ENV.fetch('PADDED_CELL_JSON', nil), junit: ENV.fetch('PADDED_CELL_JUNIT', nil) }
+      { json: ENV.fetch('PADDED_CELL_JSON', nil), junit: ENV.fetch('PADDED_CELL_JUNIT', nil),
+        coverage_map: ENV.fetch('PADDED_CELL_COVERAGE_MAP', nil) }
         .reject { |_, path| path.nil? || path.empty? }
     end
 
+    # PADDED_CELL_ASYLUM=N, or 1/true for the default 2 retries; --asylum wins.
+    def asylum_from_env
+      value = ENV.fetch('PADDED_CELL_ASYLUM', '').strip
+      return {} if value.empty? || %w[0 false no off].include?(value.downcase)
+      return { asylum: 2 } if %w[true yes on].include?(value.downcase)
+
+      { asylum: positive(Integer(value, 10)) }
+    end
+
     def parser(options)
       OptionParser.new do |opts|
         opts.banner = BANNER
@@ -98,6 +109,10 @@ module PaddedCell
       opts.on('--coverage-dir DIR', 'Write coverage reports to DIR (default: coverage, or the test helper\'s)') do
         options[:coverage_dir] = it
       end
+      opts.on('--coverage-map PATH', 'Write the lines each test ran to PATH, as JSON lines (measures ' \
+                                     'lines,methods if coverage is off; or $PADDED_CELL_COVERAGE_MAP)') do
+        options[:coverage_map] = it
+      end
       opts.on('--coverage-merge DIR,DIR', Array, 'Merge the coverage of shards (their --coverage-dir) ' \
                                                  'into one report; runs no test') do
         options[:coverage_merge] = it

data/lib/padded_cell/reporters.rb

@@ -103,6 +103,52 @@ module PaddedCell
       def escape(text) = text.to_s.scrub.gsub(INVALID, '').gsub(/[&<>"']/, ESCAPES)
     end
 
+    # --coverage-map: per test, the lines of the project it ran, one JSON
+    # object per line, in id order:
+    #
+    #   {"id":"SignTest#test_zero","file":"test/calc_test.rb","line":28,
+    #    "covers":{"lib/calc.rb":[[7,8],10,13]}}
+    #
+    # Line numbers ascend; [first, last] stands for a run of consecutive
+    # ones. Files are those the coverage report would show. A test that was
+    # not measured (its cell or worker died) is left out.
+    class CoverageMap < FileReporter
+      # coverage: the run's Chart::Accumulator
+      def initialize(path, coverage:)
+        super(path)
+        @coverage = coverage
+      end
+
+      # A first attempt, as it arrives: what it ran comes off its metadata.
+      def record(result)
+        covers = result.metadata? && result.metadata.delete(:covers)
+        @results << entry(result, covers) if covers
+      end
+
+      private
+
+      def render(entries) = entries.sort_by { it[:id] }.map { "#{JSON.generate(it)}\n" }.join
+
+      def entry(result, covers)
+        file, line = file_and_line(result)
+        { id: "#{result.klass}##{result.name}", file:, line:, covers: files(covers) }
+      end
+
+      # Two paths can name one file (a symlink): their lines are merged.
+      def files(covers)
+        files = Hash.new { |hash, name| hash[name] = [] }
+        covers.each do |path, lines|
+          name = @coverage.project_file(path)
+          files[name].concat(lines) if name
+        end
+        files.sort.to_h { |name, lines| [name, ranges(lines.uniq.sort)] }
+      end
+
+      def ranges(lines)
+        lines.slice_when { |previous, line| line != previous + 1 }.map { it.size == 1 ? it[0] : [it[0], it[-1]] }
+      end
+    end
+
     # One JSON object per test, one per line.
     class JSONLines < FileReporter
       private

data/lib/padded_cell/results.rb

@@ -88,12 +88,13 @@ module PaddedCell
     end
 
     # Marshal.dump, after replacing failures that cannot cross a pipe (an
-    # exception holding a Proc, an IO...) with plain copies.
+    # exception holding a Proc, an IO...) with plain copies. Of the metadata,
+    # only the coverage map's plain data survives.
     def dump(result)
       Marshal.dump(result)
     rescue TypeError, ArgumentError
       result.failures = result.failures.map { portable(it) }
-      result.metadata = {} if result.metadata?
+      result.metadata = result.metadata.slice(:covers) if result.metadata?
       Marshal.dump(result)
     end
 

data/lib/padded_cell/runner.rb

@@ -23,7 +23,7 @@ module PaddedCell
       paths: [], jobs: Etc.nprocessors, seed: nil, include: nil, exclude: nil, shard: [0, 1],
       isolation: nil, timeout: nil, budget: nil, asylum: nil, fail_fast: false, verbose: false, show_skips: false,
       list: false, junit: nil, json: nil, timings: 'tmp/padded_cell/timings.tsv', coverage: nil,
-      coverage_dir: nil, io: $stdout
+      coverage_dir: nil, coverage_map: nil, io: $stdout
     }.freeze
 
     attr_reader :options
@@ -31,6 +31,9 @@ module PaddedCell
     def initialize(**options)
       @options = DEFAULTS.merge(options)
       @options[:seed] ||= (ENV['SEED'] || Random.new_seed).to_i % 0xFFFF
+      # The map is made of lines, and of methods: a call to a one-line
+      # method runs no line Ruby sees.
+      @options[:coverage] ||= %i[lines methods] if @options[:coverage_map]
     end
 
     # Exit status: 0 when everything passed, 1 otherwise, 3 when only
@@ -62,7 +65,7 @@ module PaddedCell
     # Before the suite loads: nothing loaded earlier is measured.
     def start_coverage
       require_relative 'chart'
-      Chart::Accumulator.new(options[:coverage]).start
+      Chart::Accumulator.new(options[:coverage], map: !options[:coverage_map].nil?).start
     end
 
     # Two tools cannot share Ruby's Coverage.
@@ -97,10 +100,16 @@ module PaddedCell
       nothing_ran = batches.empty?
       reporter = build_reporter
       reporter.start
+      # First attempts only, as with the coverage it is made of.
+      map = Reporters::CoverageMap.new(options[:coverage_map], coverage: @coverage) if options[:coverage_map]
       retried = []
       @coverage&.snapshot
-      status = dispatch(tests, batches, reporter, retried) { |index, result| timings[ids[index]] = result.time }
+      status = dispatch(tests, batches, reporter, retried) do |index, result|
+        timings[ids[index]] = result.time
+        map&.record(result)
+      end
       reporter.report
+      map&.report
       report_asylum(retried)
       covered = @coverage ? report_coverage(status, reporter) : true
       Timings.save(options[:timings], timings)

data/lib/padded_cell/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PaddedCell
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/padded_cell/worker.rb

@@ -55,6 +55,8 @@ module PaddedCell
         Results.crashed(klass, name, "after_fork hook failed: #{setup_error.class}: #{setup_error.message}")
       elsif @isolation == :test
         Cell.run(klass, name, seed: @seed, limits: @limits, close: [socket], probe: @probe)
+      elsif @probe
+        @probe.measure { Cell.execute(klass, name) }
       else
         Cell.execute(klass, name)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: padded_cell
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Abdelkader Boudih