Class: Mutineer::CoverageMap

Inherits:
Object
  • Object
show all
Defined in:
lib/mutineer/coverage_map.rb

Overview

Maps (source_file, line) -> [test_files] so each mutant runs only against the tests that actually exercise its line. Built once, then queried per mutant via #tests_for. Persisted to .mutineer/coverage.json with a content-based digest. A later run recaptures every test when a run input, a loaded file, or the shape of a source changes. A change that stays inside method bodies, without moving a line or editing a method that ran at load, recaptures only the tests in that source's map entries (#421).

Keys are "file:line" strings (relative to project_root) everywhere, in memory and on disk, so load/save needs no key transformation.

Constant Summary collapse

DEFAULT_CAPTURE_TIMEOUT =

Seconds per coverage subprocess before the parent kills it.

120
COMBINED_TIMEOUT_FACTOR =

The combined clean check runs the clean-check test files in one process. Its deadline is this factor times the summed capture seconds of those files, and never less than the capture timeout.

1.5
RESULT_FD =

File descriptor in a capture subprocess that carries the JSON result to the parent. Stdout stays free for test output, which goes to File::NULL.

3
RESULT_GRACE =

Seconds a capture waits for its result after the child exits in time. The result is already in the pipe then; the wait only lets the reader thread run, even when the capture deadline has passed (#129).

1
REDACTION_PATH =

The redaction module, by absolute path, for the subprocess scripts: they write a failing test's report, or a load error, to the inherited stderr, and either can quote DATABASE_URL.

File.expand_path("redaction.rb", __dir__)
CLEAN_FAILURE_DETAIL_LIMIT =

Cap for a failing clean-suite report on the SmokeCheckError line (#360).

800
NARROW_LOAD_LINES =

Key in coverage.json that marks a map built after #426. Standalone capture no longer credits every test with lines that ran only while the sources loaded. A standalone cache without this key was built the old way and is rebuilt once. Boot and daemon maps already omitted those lines; a hit there does not read the key.

"narrow_load_lines"
PARTIAL_CACHE_KEYS =

Keys a cache needs before a method-body edit can recapture part of the map (#421). A cache saved before these keys existed is rebuilt once.

%w[run_inputs sources skeletons tests load_method_bodies].freeze
LOAD_LINE_PAIRS =

Key for the paired tests that kept load-only lines when the map was saved. Pairing.infer_tests reads files that are not in this run. An exact spec replaces split tests, and the content digest does not see a file the run did not select. A standalone hit rebuilds when this list no longer matches.

"load_line_pairs"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source_paths:, test_paths:, cache_dir: ".mutineer", load_paths: ["lib"], project_root: Dir.pwd, capture_timeout: DEFAULT_CAPTURE_TIMEOUT, boot_path: nil, framework: "minitest", verbose: false, require_paths: [], coverage_from: nil) ⇒ CoverageMap

Returns a new instance of CoverageMap.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
# File 'lib/mutineer/coverage_map.rb', line 143

def initialize(source_paths:, test_paths:, cache_dir: ".mutineer",
               load_paths: ["lib"], project_root: Dir.pwd,
               capture_timeout: DEFAULT_CAPTURE_TIMEOUT, boot_path: nil,
               framework: "minitest", verbose: false, require_paths: [], coverage_from: nil)
  @source_paths = Array(source_paths).map { |path| FsPath.read(path) }
  @require_paths = Array(require_paths).map { |path| FsPath.read(path) }
  @test_paths   = Array(test_paths).map { |path| FsPath.read(path) }
  @cache_dir    = FsPath.read(cache_dir)
  @coverage_from = coverage_from && FsPath.read(coverage_from)
  @load_paths   = Array(load_paths).map { |path| FsPath.read(path) }
  @project_root = FsPath.read(project_root)
  @capture_timeout = capture_timeout
  @boot_path    = boot_path
  @framework    = framework || "minitest"
  @verbose      = verbose
  @map          = {}
  @failed_test_files = []
  @failed_clean_tests = []
  @failed_clean_details = {}
  @clean_timeouts = {}
  @load_lines   = Set.new
  @load_methods = Set.new
  @timings      = {}
  @loaded_dependencies = {}
  @phase_a_ran  = false
end

Instance Attribute Details

#clean_timeouts ⇒ Hash{String => Numeric} (readonly)

Clean checks that hit their deadline, keyed like #failed_clean_tests, with the deadline in seconds. Each key is also in #failed_clean_tests, so the run still stops, but JobPlan.abort_if_unclean! reports a timeout, not a red suite.

Returns:

  • (Hash{String => Numeric})


84
85
86
# File 'lib/mutineer/coverage_map.rb', line 84

def clean_timeouts
  @clean_timeouts
end

#failed_clean_details ⇒ Object (readonly)

Returns the value of attribute failed_clean_details.



75
76
77
# File 'lib/mutineer/coverage_map.rb', line 75

def failed_clean_details
  @failed_clean_details
end

#failed_clean_tests ⇒ Object (readonly)

Returns the value of attribute failed_clean_tests.



75
76
77
# File 'lib/mutineer/coverage_map.rb', line 75

def failed_clean_tests
  @failed_clean_tests
end

#failed_test_files ⇒ Object (readonly)

Returns the value of attribute failed_test_files.



75
76
77
# File 'lib/mutineer/coverage_map.rb', line 75

def failed_test_files
  @failed_test_files
end

#load_lines ⇒ Set<String> (readonly)

The source lines that ran while the app booted or the sources and the --require files loaded, before any test ran, as a Set of "file:line" keys like #map's (#187, #217). A mutant on such a line can change a value computed before the mutant was applied, so its verdict is not trusted (ran_at_load).

Returns:

  • (Set<String>)


93
94
95
# File 'lib/mutineer/coverage_map.rb', line 93

def load_lines
  @load_lines
end

#load_methods ⇒ Set<String> (readonly)

The source methods that were called while the app booted or the sources and the --require files loaded, as a Set of "file:line:column" keys of their def (#209). Line coverage cannot tell this for a one-line or endless method: its def line counts when the method is defined.

Returns:

  • (Set<String>)


101
102
103
# File 'lib/mutineer/coverage_map.rb', line 101

def load_methods
  @load_methods
end

#map ⇒ Object (readonly)

Returns the value of attribute map.



75
76
77
# File 'lib/mutineer/coverage_map.rb', line 75

def map
  @map
end

#phase_a_ran ⇒ Object (readonly)

Returns the value of attribute phase_a_ran.



75
76
77
# File 'lib/mutineer/coverage_map.rb', line 75

def phase_a_ran
  @phase_a_ran
end

#project_root ⇒ Object (readonly)

Returns the value of attribute project_root.



75
76
77
# File 'lib/mutineer/coverage_map.rb', line 75

def project_root
  @project_root
end

#timings ⇒ Hash{String => Float} (readonly)

Seconds each test file took to capture, keyed by project-relative path (#203). #order_tests runs the cheaper files first.

Returns:

  • (Hash{String => Float})


107
108
109
# File 'lib/mutineer/coverage_map.rb', line 107

def timings
  @timings
end

Class Method Details

.from_data(map:, failed_test_files:, project_root:, failed_clean_tests: [], failed_clean_details: {}, load_lines: [], load_methods: [], timings: {}, clean_timeouts: {}) ⇒ Mutineer::CoverageMap

Build a QUERY-ONLY map from data captured elsewhere (the daemon builds the map app-side and ships map + failed_test_files over IPC; the tool reconstructs it here for per-mutant selection). Skips the capture machinery entirely: only the three fields #tests_for / #method_uncapturable? read are set.

Parameters:

  • map (Hash) —

    the "file:line" => [test_files] map.

  • failed_test_files (Array<String>) —

    test files whose capture failed.

  • project_root (String) —

    project root (for path relativization).

  • failed_clean_tests (Array<String>) (defaults to: []) —

    test files whose unmutated run failed.

  • failed_clean_details (Hash{String => String}) (defaults to: {}) —

    capped failure report per failed clean test (issue #360).

  • load_lines (Array<String>, Set<String>) (defaults to: []) —

    "file:line" keys that ran at load (#load_lines).

  • load_methods (Array<String>, Set<String>) (defaults to: []) —

    "file:line:column" keys of methods called at load (#load_methods).

  • timings (Hash{String => Float}) (defaults to: {}) —

    capture seconds per test file (#timings).

  • clean_timeouts (Hash{String => Numeric}) (defaults to: {}) —

    clean checks that timed out (#clean_timeouts).

Returns:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
# File 'lib/mutineer/coverage_map.rb', line 127

def self.from_data(map:, failed_test_files:, project_root:, failed_clean_tests: [],
                   failed_clean_details: {}, load_lines: [],
                   load_methods: [], timings: {}, clean_timeouts: {})
  instance = allocate
  instance.instance_variable_set(:@map, map || {})
  instance.instance_variable_set(:@timings, timings || {})
  instance.instance_variable_set(:@load_lines, Set.new(load_lines || []))
  instance.instance_variable_set(:@load_methods, Set.new(load_methods || []))
  instance.instance_variable_set(:@failed_test_files, failed_test_files || [])
  instance.instance_variable_set(:@failed_clean_tests, failed_clean_tests || [])
  instance.instance_variable_set(:@failed_clean_details, failed_clean_details || {})
  instance.instance_variable_set(:@clean_timeouts, clean_timeouts || {})
  instance.instance_variable_set(:@project_root, FsPath.read(project_root))
  instance
end

Instance Method Details

#abs_load_paths ⇒ Array<String> (private)

Returns absolute load paths.

Returns:

  • (Array<String>) —

    absolute load paths.



2765
# File 'lib/mutineer/coverage_map.rb', line 2765

def abs_load_paths   = @load_paths.map { |p| absolute(p) }

#abs_preload_paths ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The sources, then the --require files, in the order standalone Runner.execute requires them before it forks the mutants (#217).

Returns:

  • (Array<String>) —

    absolute paths.



2760
# File 'lib/mutineer/coverage_map.rb', line 2760

def abs_preload_paths = abs_source_paths + @require_paths.map { |p| absolute(p) }

#abs_source_paths ⇒ Array<String> (private)

Returns absolute source paths.

Returns:

  • (Array<String>) —

    absolute source paths.



2753
# File 'lib/mutineer/coverage_map.rb', line 2753

def abs_source_paths = @source_paths.map { |p| absolute(p) }

#absolute(path) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Expands a path relative to the project root (see ProjectPath.absolute).

Parameters:

  • path (String) —

    path to expand.

Returns:

  • (String) —

    absolute path.



2779
# File 'lib/mutineer/coverage_map.rb', line 2779

def absolute(path) = ProjectPath.absolute(path, @project_root)

#accept_capture_payload(test_path, payload) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Records a wrapped capture: assertion failures go to #failed_clean_tests; successful coverage is inverted into the map. Capture crashes stay in #failed_test_files via #fail_test.

Parameters:

  • test_path (String) —

    test file path.

  • payload (Hash) —

    wrapped capture with string keys.



918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
# File 'lib/mutineer/coverage_map.rb', line 918

def accept_capture_payload(test_path, payload)
  unless wrapped_capture?(payload)
    fail_test(test_path, "invalid coverage output: missing pass/coverage payload")
    return
  end

  record_loaded(payload["loaded_files"])
  record_load(payload["load_coverage"])

  unless payload["passed"]
    record_failed_clean(relativize(test_path), payload["failure_report"])
    return
  end

  coverage = payload["coverage"]
  return unless coverage.is_a?(Hash)

  # Post-load counts only. Standalone capture clears the load snapshot
  # before the test runs; a fork capture already discarded the boot delta.
  record(map_coverage(coverage), test_path)
  # Lines that ran only while the sources loaded. The paired test keeps
  # them, so a reload mutant a test checks through a value built at load
  # still runs (#348). An unrelated test does not.
  record_paired_load_lines(payload["load_coverage"], coverage, test_path)
end

#accept_fork_payload(test_path, payload) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Records a #fork_capture result. Hash = capture result, String = error diagnostic from the child, :timeout = the capture deadline passed, nil = pipe gone / empty. The String diagnostic is what becomes an :uncapturable status.

Parameters:

  • test_path (String) —

    test file path.

  • payload (Hash, String, Symbol, nil) —

    what #fork_capture returned.



774
775
776
777
778
779
780
781
782
783
# File 'lib/mutineer/coverage_map.rb', line 774

def accept_fork_payload(test_path, payload)
  case payload
  when Hash then accept_capture_payload(test_path, payload)
  when :timeout then fail_test(test_path, "timed out after #{@capture_timeout}s")
  when String
    fail_test(test_path, @verbose ? "fork capture failed: #{payload}" :
      "fork capture produced no result (re-run with --verbose for the error)")
  else fail_test(test_path, "fork capture produced no result")
  end
end

#accepted_capture ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The parsed --coverage-from capture, once it fits this run.

Returns:

  • (Hash) —

    the parsed coverage.json.

Raises:



607
608
609
610
611
612
613
614
615
616
617
618
619
# File 'lib/mutineer/coverage_map.rb', line 607

def accepted_capture
  if File.expand_path(@coverage_from) == File.expand_path(cache_path)
    raise CoverageFromError, "--coverage-from #{@coverage_from} is this run's own cache; give the run another --cache-dir"
  end

  cached = JSON.parse(File.read(@coverage_from, encoding: "UTF-8"))
  reason = capture_mismatch(cached)
  raise CoverageFromError, "--coverage-from #{@coverage_from} cannot be reused: #{reason}" if reason

  cached
rescue SystemCallError, JSON::ParserError => e
  raise CoverageFromError, "--coverage-from #{@coverage_from} cannot be read: #{e.message}"
end

#add_covering_test(key, rel_test) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Adds rel_test to the map entry for key, in @test_paths order. A partial recapture appends a test that a full capture would have recorded earlier. Sorting by the run's test order keeps the two maps equal (#421). A full capture appends in order, so it takes the fast path: sorting on every append made capture quadratic in the test count.

Parameters:

  • key (String) —

    a "file:line" map key.

  • rel_test (String) —

    project-relative test path.



1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
# File 'lib/mutineer/coverage_map.rb', line 1621

def add_covering_test(key, rel_test)
  list = (@map[key] ||= [])
  last = list.last
  if last.nil? || test_index(last) < test_index(rel_test)
    list << rel_test
  else
    list << rel_test unless list.include?(rel_test)
    list.sort_by! { |test| test_index(test) }
  end
end

#app_or_lib_source?(source_rel) ⇒ Boolean (private)

True when pairing gives this source a mirrored test directory.

Parameters:

  • source_rel (String) —

    project-relative source path.

Returns:

  • (Boolean)


375
376
377
# File 'lib/mutineer/coverage_map.rb', line 375

def app_or_lib_source?(source_rel)
  source_rel.start_with?("app/", "lib/")
end

#apply_cache(cached) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Copies a saved map into this object. Boot mode keeps the load lines it just read from the live boot.

Parameters:

  • cached (Hash) —

    parsed coverage.json.



2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
# File 'lib/mutineer/coverage_map.rb', line 2080

def apply_cache(cached)
  @map = cached["map"] || {}
  @timings = cached["timings"] || {}
  unless @boot_path
    @load_lines = Set.new(cached["load_lines"])
    @load_methods = Set.new(cached["load_methods"])
  end
  @failed_test_files = Array(cached["failed_test_files"])
  @failed_clean_tests = []
  @failed_clean_details = {}
  @clean_timeouts = {}
  @loaded_dependencies = cached["dependencies"] || {}
end

#apply_partial(plan, cached, after_fork) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Rebuilds the tests in plan and keeps the rest. Returns false when the recaptured load snapshot disagrees with the cache: the caller then captures every test. A kept test is not credited with another source's load-only lines, because those entries are left as the full capture stored them and #record_paired_load_lines does not add them back.

Parameters:

  • plan (Hash) —

    the plan from #partial_plan.

  • cached (Hash) —

    parsed coverage.json.

  • after_fork (Proc, nil) —

    boot-mode fork hook.

Returns:

  • (Boolean) —

    true when the partial map was saved.



2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
# File 'lib/mutineer/coverage_map.rb', line 2158

def apply_partial(plan, cached, after_fork)
  apply_cache(cached)
  removed = plan["removed"]
  recapture = plan["recapture"]
  (removed + recapture).each { |rel| drop_test(rel) }
  @failed_test_files -= (removed + recapture)
  @collect_load = true
  @seen_load_lines = nil
  @seen_load_methods = nil
  @test_paths.each do |path|
    capture_one(path, after_fork) if recapture.include?(relativize(path))
  end
  @collect_load = false
  return false if !@boot_path && recapture.any? && partial_load_diverged?(cached)

  refresh_dependency_fingerprints(plan["changed_sources"] + recapture)
  # A removed test keeps its fingerprint: a kept test may still load
  # that file, and the map does not record which test loaded what.
  sort_map_entries
  @phase_a_ran = true if recapture.any?
  warn_recaptured(recapture.size, @test_paths.size)
  checked = clean_check_test_paths
  verify_cached_clean(after_fork: after_fork,
                      test_paths: checked.reject { |test| recapture.include?(relativize(test)) })
  verify_combined_clean(after_fork: after_fork)
  warn_unchecked("coverage cache", checked.size)
  save
  true
end

#await_child(pid, deadline, &read) ⇒ Array(Process::Status, Object) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Waits for capture child pid, which leads its own process group, while a thread runs the block to read the child's result. One deadline bounds the run, the read, and the reap. Past it, the whole group gets SIGKILL, so a process the test started does not outlive a hung capture. Process.detach owns reaping. The same deadline and group kill as DaemonServer#wait_verdict, plus a reader, because the child reports through a pipe.

A child that exits before the deadline has written its result, so the reader gets the time left, and at least RESULT_GRACE seconds, to finish.

Parameters:

  • pid (Integer) —

    child pid, also its process group id.

  • deadline (Float) —

    a CLOCK_MONOTONIC time.

Yield Returns:

  • (Object) —

    what the child wrote.

Returns:

  • (Array(Process::Status, Object)) —

    the exit status and the block's value (nil when the reader did not finish); [nil, nil] after a timeout.



1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
# File 'lib/mutineer/coverage_map.rb', line 1207

def await_child(pid, deadline, &read)
  waiter = Process.detach(pid)
  reader = Thread.new(&read)
  reader.report_on_exception = false
  return [nil, nil] unless waiter.join(remaining(deadline))

  [waiter.value, reader.join([remaining(deadline), RESULT_GRACE].max)&.value]
ensure
  kill_group(pid, waiter) if waiter&.alive?
  reader&.kill
end

#blank_method_bodies(source, ranges) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

source with every method-body byte range replaced by one marker. Nested bodies are one marker: the outer range already covers them.

Parameters:

  • source (String) —

    source bytes.

  • ranges (Array<Array(Integer, Integer)>) —

    half-open byte ranges.

Returns:

  • (String) —

    binary skeleton text.



2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
# File 'lib/mutineer/coverage_map.rb', line 2406

def blank_method_bodies(source, ranges)
  return source if ranges.empty?

  skip = Array.new(source.bytesize, false)
  ranges.each do |start, finish|
    next if start.negative? || finish > source.bytesize

    (start...finish).each { |index| skip[index] = true }
  end
  out = +"".b
  source.each_byte.with_index do |byte, index|
    if skip[index]
      out << 0 unless index.positive? && skip[index - 1]
    else
      out << byte
    end
  end
  out
end

#body_byte_range(node) ⇒ Array(Integer, Integer)? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Byte range of the body of node, after its name and parameters. Nil when the body is empty. A def with rescue or ensure has a BeginNode body that starts at the def keyword, so the range starts where the signature ends: a same-line name or parameter edit is not a body edit.

Parameters:

  • node (Prism::DefNode) —

    a method definition.

Returns:

  • (Array(Integer, Integer), nil) —

    half-open byte range.



2390
2391
2392
2393
2394
2395
2396
2397
# File 'lib/mutineer/coverage_map.rb', line 2390

def body_byte_range(node)
  loc = node.body&.location
  return nil unless loc

  signature_end = [node.name_loc, node.parameters&.location, node.rparen_loc].compact.map(&:end_offset).max
  start = [loc.start_offset, signature_end].max
  start < loc.end_offset ? [start, loc.end_offset] : nil
end

#body_digest_at(key) ⇒ String? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Digest of the method body at the def named by key, in the file as it is now. Nil when that def is gone or the file does not parse.

Parameters:

  • key (String) —

    a "file:line:column" load-method key.

Returns:

  • (String, nil) —

    hex digest.



2475
2476
2477
2478
2479
2480
2481
# File 'lib/mutineer/coverage_map.rb', line 2475

def body_digest_at(key)
  rel, line, column = split_method_key(key)
  text = method_bodies(rel)&.[]([line, column])
  return nil if text.nil?

  Digest::SHA256.hexdigest(text)
end

#build_or_load ⇒ Object

Standalone entry: load the cached map when the content digest matches, otherwise rebuild from subprocesses and overwrite the cache.



172
173
174
175
# File 'lib/mutineer/coverage_map.rb', line 172

def build_or_load
  warn_external_sources
  cached_or { run_phase_a }
end

#build_via_fork(after_fork: nil) ⇒ Object

Boot-mode build: Coverage is already running in the parent (started before the app booted, so booted source lines are instrumented). A clean ruby subprocess has no booted env, so per-test coverage is captured by FORKING the booted parent instead. Inverts into the same map #tests_for reads, and reuses the digest cache (the digest mixes in the boot file so a boot cache never collides with a standalone one).

The lines that ran during boot are read here on every run, cache or not: the boot runs every time, and no test is credited with those lines.



186
187
188
189
190
191
192
193
# File 'lib/mutineer/coverage_map.rb', line 186

def build_via_fork(after_fork: nil)
  warn_external_sources
  # Matched by real path in #record_load: a Coverage key is the path as
  # required, which can differ from the configured one (/var, /private/var).
  booted = Coverage.running? ? Coverage.peek_result : {}
  record_load(booted.transform_values { |v| v.is_a?(Hash) ? load_entry(v[:lines], v[:methods]) : v })
  cached_or(after_fork: after_fork) { run_phase_a_via_fork(after_fork: after_fork) }
end

#cache_hit?(cached) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when cached is a complete map for this exact run: same digest, same loaded files, and the keys a later partial recapture needs.

Parameters:

  • cached (Hash, nil) —

    parsed coverage.json.

Returns:

  • (Boolean)


2058
2059
2060
2061
2062
2063
# File 'lib/mutineer/coverage_map.rb', line 2058

def cache_hit?(cached)
  cached && cached["digest"] == @digest && dependencies_match?(cached) &&
    cached.key?("load_methods") && cached.key?("timings") &&
    parallel_workers_match?(cached) && standalone_load_lines_current?(cached) &&
    partial_cache?(cached)
end

#cache_path ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the cache path.

Returns:

  • (String) —

    cache file path.



2702
# File 'lib/mutineer/coverage_map.rb', line 2702

def cache_path = File.join(@cache_dir, "coverage.json")

#cached_or(after_fork: nil) { ... } ⇒ Mutineer::CoverageMap (private)

Shared cache dance for both build paths: hit the digest-keyed cache, else yield to populate @map and persist it. A digest match is not proof that today's unmutated suite still passes, so a hit re-checks the tests a mutant can run (#clean_check_test_paths), alone and then together (#398).

Parameters:

  • after_fork (Proc, nil) (defaults to: nil) —

    boot-mode fork hook forwarded to a clean re-check.

Yields:

  • when the cache is missing or stale.

Returns:



486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
# File 'lib/mutineer/coverage_map.rb', line 486

def cached_or(after_fork: nil)
  @digest = compute_digest
  return reuse_capture(after_fork) if @coverage_from

  cached = read_cache
  # A cache from before load methods (#209), test timings (#203), the
  # standalone load-line narrowing (#426), or partial recapture (#421)
  # rebuilds once. A cache that does not record this process's
  # PARALLEL_WORKERS value rebuilds too. Rails reads that value inside
  # parallelize, so a map from another worker count selects the wrong
  # tests. The daemon writes this same file. Boot mode reads its load
  # lines and methods from the live boot instead (#build_via_fork), but
  # its map from before #209 lacks the `def` lines of the methods each
  # test called.
  if cache_hit?(cached)
    apply_cache(cached)
    recaptured = retry_failed_captures(after_fork)
    warn_incomplete unless @failed_test_files.empty?
    checked = clean_check_test_paths
    # A retried capture already ran its test clean, so it does not run alone again.
    verify_cached_clean(after_fork: after_fork,
                        test_paths: checked.reject { |t| recaptured.include?(relativize(t)) })
    verify_combined_clean(after_fork: after_fork)
    warn_unchecked("coverage cache hit", checked.size)
    save
    return self
  end

  plan = partial_plan(cached)
  return self if plan && apply_partial(plan, cached, after_fork)

  yield
  verify_combined_clean(after_fork: after_fork)
  warn_unchecked("coverage capture", clean_check_test_paths.size, miss: true)
  save
  self
end

#capture(test_path) ⇒ Object (private)

Spawns a fresh ruby reading an inline script from stdin. A fork would miss already-loaded app lines, so Coverage must start in a clean process before any source is loaded. Returns the wrapped capture payload (passed + coverage), or nil when the subprocess failed (logged + skipped).



873
874
875
876
877
878
879
880
881
882
883
884
# File 'lib/mutineer/coverage_map.rb', line 873

def capture(test_path)
  status, out = spawn_script(subprocess_script(test_path))
  return fail_test(test_path, "timed out after #{@capture_timeout}s") unless status
  return fail_test(test_path, "subprocess exited #{status.exitstatus}") unless status.success?

  parsed = JSON.parse(out)
  return fail_test(test_path, "invalid coverage output: missing pass/coverage payload") unless wrapped_capture?(parsed)

  parsed
rescue JSON::ParserError => e
  fail_test(test_path, "invalid coverage output: #{e.message}")
end

#capture_loaded_files ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Project-local .rb files loaded in this process at capture time.

Returns:

  • (Array<String>) —

    absolute realpaths.



1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
# File 'lib/mutineer/coverage_map.rb', line 1973

def capture_loaded_files
  root = FsPath.read(project_root_real)
  prefix = root.b
  prefix += "/".b unless prefix.end_with?("/".b)
  $LOADED_FEATURES.filter_map do |f|
    next unless f.b.end_with?(".rb".b)

    abs = File.realpath(f)
    FsPath.read(abs) if FsPath.bytes_start_with?(abs, prefix)
  rescue Errno::ENOENT
    nil
  end
end

#capture_mismatch(cached) ⇒ String? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Why a capture does not fit this run, or nil when it does.

Parameters:

  • cached (Object) —

    the parsed coverage.json.

Returns:

  • (String, nil)


626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
# File 'lib/mutineer/coverage_map.rb', line 626

def capture_mismatch(cached)
  return "it is not a coverage cache" unless cached.is_a?(Hash) && cached["map"].is_a?(Hash)
  unless cached["sources"] && cached["owners"] && cached["inputs"]
    return "it has no source fingerprints; capture it again with this version and --rails/--boot"
  end
  return "its entries are not the shape a coverage cache saves; capture it again" unless well_formed_capture?(cached)
  return "its tests, --require files, boot file, load paths, framework or test seed differ, or an older version made it; capture it again" unless cached["inputs"] == compute_digest(inputs_only: true)

  fingerprints = source_fingerprints
  missing = fingerprints.keys - cached["sources"].keys
  return "it was not captured over #{missing.join(', ')}" if missing.any?

  changed = fingerprints.reject { |rel, fingerprint| cached["sources"][rel] == fingerprint }.keys
  return "#{changed.join(', ')} changed since the capture" if changed.any?

  owners = ownership_paths - cached["owners"]
  return "#{owners.join(', ')} appeared since the capture and can own a split test" if owners.any?

  # The capture can list owners of sources outside this run, so compare
  # with the disk, not with this run's owners.
  gone = cached["owners"].reject { |rel| File.file?(absolute(rel)) }
  return "#{gone.join(', ')} disappeared since the capture and could own a split test" if gone.any?

  return "a file its tests loaded changed since the capture" unless dependencies_match?(cached)
  unless parallel_workers_match?(cached)
    return "it was captured with PARALLEL_WORKERS=#{cached['parallel_workers'].inspect}, " \
           "this run has #{ENV.fetch('PARALLEL_WORKERS', nil).inspect}"
  end

  failed = Array(cached["failed_test_files"])
  return "capture failed for #{failed.join(', ')}" if failed.any?

  moved = load_mismatch(cached, fingerprints.keys.to_set)
  return nil if moved.empty?

  "lines of #{moved.join(', ')} ran at load in only one of the capture and this run: loading the capture's " \
    "other sources ran them. Under --strategy redefine, eager-load in both (config.eager_load = true)"
end

#capture_one(test_path, after_fork) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Captures one test file, standalone or by fork, and records the result.

Parameters:

  • test_path (String) —

    test file path.

  • after_fork (Proc, nil) —

    boot-mode fork hook.



1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
# File 'lib/mutineer/coverage_map.rb', line 1034

def capture_one(test_path, after_fork)
  if @boot_path
    accept_fork_payload(test_path, timed(test_path) do
      fork_capture(absolute(test_path), abs_source_paths, after_fork)
    end)
  else
    payload = timed(test_path) { capture(test_path) }
    accept_capture_payload(test_path, payload) if payload
  end
end

#clean_check_script(test_paths) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds a pass/fail-only subprocess script (no coverage instrumentation).

Parameters:

  • test_paths (Array<String>) —

    test file paths.

Returns:

  • (String) —

    Ruby script text.



1337
1338
1339
# File 'lib/mutineer/coverage_map.rb', line 1337

def clean_check_script(test_paths)
  @framework == "rspec" ? rspec_clean_check_script(test_paths) : minitest_clean_check_script(test_paths)
end

#clean_check_test_paths ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The tests the clean check runs: the tests that cover a line of this run's sources (#398). A mutant runs only tests from the map (JobPlan.coverage_selection), so a test outside this set never runs with a mutant and cannot change a verdict. Mutants exist only in the sources, so only source keys count: standalone capture also maps the other project files a test ran, its own file too. A map with no source key keeps every test, because the daemon then runs every test for each mutant. A new way to choose a mutant's tests must add those tests here, or a red test could reach a mutant run.

Returns:

  • (Array<String>) —

    the --test paths in this set, in their order.



536
537
538
539
540
541
542
543
544
# File 'lib/mutineer/coverage_map.rb', line 536

def clean_check_test_paths
  @source_rels ||= @source_paths.to_set { |p| relativize(absolute(p)) }
  covering = @map.each_with_object(Set.new) do |(key, tests), set|
    set.merge(tests) if @source_rels.include?(key_source(key))
  end
  return @test_paths if covering.empty?

  @test_paths.select { |t| covering.include?(relativize(t)) }
end

#combined_clean_timeout(test_paths) ⇒ Numeric (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The combined clean check's deadline: COMBINED_TIMEOUT_FACTOR times the summed capture seconds of test_paths, and at least @capture_timeout. One process runs them all, so the per-file capture timeout alone stops a green suite that is just slow.

Parameters:

  • test_paths (Array<String>) —

    the tests the combined check runs.

Returns:

  • (Numeric) —

    seconds.



1078
1079
1080
1081
# File 'lib/mutineer/coverage_map.rb', line 1078

def combined_clean_timeout(test_paths)
  measured = test_paths.sum { |t| @timings[relativize(t)].to_f }
  [@capture_timeout, (measured * COMBINED_TIMEOUT_FACTOR).ceil].max
end

#compute_digest(inputs_only: false) ⇒ Object (private)

Digest each file's ROLE + relative path + content length + content, plus the load_paths. Without role/path/length delimiters the digest collides (("ab","c") == ("a","bc")) and is blind to source/test role swaps, silently accepting a stale cached map.

Parameters:

  • inputs_only (Boolean) (defaults to: false) —

    leave out the sources and their owners.



2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
# File 'lib/mutineer/coverage_map.rb', line 2559

def compute_digest(inputs_only: false)
  d = Digest::SHA256.new
  digest_group(d, "source", @source_paths) unless inputs_only
  digest_group(d, "test", @test_paths)
  # One group per file: digest_group sorts, and the load order matters.
  @require_paths.each { |p| digest_group(d, "require", [digest_path(p)]) }
  digest_group(d, "boot", [digest_path(@boot_path)]) if @boot_path
  (inputs_only ? [] : ownership_paths).each do |rel|
    d.update("owner\0")
    d.update(rel)
    d.update("\0")
  end
  @load_paths.sort.each { |lp| d.update("loadpath\0#{lp}\0") }
  d.update("framework\0#{@framework}\0")
  digest_test_seed(d)
  d.hexdigest
end

#conventional_test_dir?(dir) ⇒ Boolean (private)

True when dir is test, spec, or a directory under one of them.

Parameters:

  • dir (String) —

    project-relative directory.

Returns:

  • (Boolean)


396
397
398
# File 'lib/mutineer/coverage_map.rb', line 396

def conventional_test_dir?(dir)
  dir == "test" || dir == "spec" || dir.start_with?("test/", "spec/")
end

#covered_source_files ⇒ Object (private)

Source rel-paths that received coverage from any successful capture.



298
299
300
# File 'lib/mutineer/coverage_map.rb', line 298

def covered_source_files
  @map.keys.map { |k| k.rpartition(":").first }.to_set
end

#credit_load_only_line?(rel_source, rel_test) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Whether rel_test keeps lines of rel_source that ran only at load. A paired test in the run does. When none of the run's tests pair with the source, every test does.

Parameters:

  • rel_source (String) —

    project-relative source path.

  • rel_test (String) —

    project-relative test path.

Returns:

  • (Boolean)


1722
1723
1724
1725
# File 'lib/mutineer/coverage_map.rb', line 1722

def credit_load_only_line?(rel_source, rel_test)
  paired = paired_tests_in_run(rel_source)
  paired.empty? || paired.include?(rel_test)
end

#current_load_method_bodies ⇒ Hash{String => String} (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Body digest of each method in #load_methods, keyed the same way. "missing" marks a def the file no longer has at that line.

Returns:

  • (Hash{String => String})


2465
2466
2467
# File 'lib/mutineer/coverage_map.rb', line 2465

def current_load_method_bodies
  @load_methods.to_h { |key| [key, body_digest_at(key) || "missing"] }
end

#dependencies_match?(cached, except: []) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when the cached map recorded support-file fingerprints and they still match. Missing validity data is a miss (rebuild).

Parameters:

  • cached (Hash) —

    parsed coverage.json.

  • except (Array<String>) (defaults to: []) —

    project-relative paths whose fingerprint may differ. A method-body edit of a run source is checked by the skeleton instead (#421). Any other loaded file still has to match.

Returns:

  • (Boolean)


2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
# File 'lib/mutineer/coverage_map.rb', line 2039

def dependencies_match?(cached, except: [])
  deps = cached["dependencies"]
  return false unless deps.is_a?(Hash)

  skip = except.to_set
  deps.all? do |rel, fingerprint|
    next true if skip.include?(rel)

    abs = absolute(rel)
    File.file?(abs) && file_fingerprint(abs) == fingerprint
  end
end

#describe_status(status) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Human description of a child Process::Status for capture diagnostics.

Parameters:

  • status (Process::Status) —

    the reaped child status.

Returns:

  • (String) —

    e.g. "killed by signal 9 (SIGKILL)" or "exit status 1".



860
861
862
863
864
865
866
867
# File 'lib/mutineer/coverage_map.rb', line 860

def describe_status(status)
  if status.signaled?
    sig = status.termsig
    "killed by signal #{sig}#{Signal.signame(sig) ? " (SIG#{Signal.signame(sig)})" : ''}"
  else
    "exit status #{status.exitstatus.inspect}"
  end
end

#digest_group(digest, role, paths) ⇒ Array(String, String, Array<String>) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Groups a digest with its role and paths.

Parameters:

  • digest (String) —

    digest string.

  • role (String) —

    digest role.

  • paths (Array<String>) —

    paths in the digest group.

Returns:

  • (Array(String, String, Array<String>)) —

    grouped digest data.



2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
# File 'lib/mutineer/coverage_map.rb', line 2671

def digest_group(digest, role, paths)
  paths.sort.each do |p|
    # Bytes, not a locale read: a magic-comment encoding such as EUC-JP
    # is not valid UTF-8, and the digest is of the file's bytes (#346).
    content = File.binread(absolute(p))
    digest.update(role)
    digest.update("\0")
    digest.update(relativize(absolute(p)))
    digest.update("\0")
    digest.update(content.bytesize.to_s)
    digest.update("\0")
    digest.update(content)
    digest.update("\0")
  end
end

#digest_path(path) ⇒ Object (private)

boot_path and require_paths are require-style paths (e.g. "config/environment", no extension); resolve one to the file require loads: the path itself, then ".rb", then a native extension. A folder of the same name (lib/my_gem/ next to lib/my_gem.rb) is not the file.



2659
2660
2661
2662
# File 'lib/mutineer/coverage_map.rb', line 2659

def digest_path(path)
  ["", ".rb", ".#{RbConfig::CONFIG['DLEXT']}"].map { |ext| "#{path}#{ext}" }
                                            .find { |p| File.file?(absolute(p)) } || "#{path}.rb"
end

#digest_test_seed(digest) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Adds the test seed inputs to digest. The seed sets the test order, and the order can change which lines run (#282). Minitest: the configured seed. A test helper that changes SEED is not digested, like any other helper edit. RSpec: the pinned seed, SPEC_OPTS, and the project .rspec files. ~/.rspec and a config.seed in a spec helper are not digested; a helper edit is seen when that file is part of the capture. #compute_digest and #run_inputs_digest share this, so a seed change never reaches a partial recapture (#421).

Parameters:

  • digest (Digest::SHA256) —

    the digest to update.



2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
# File 'lib/mutineer/coverage_map.rb', line 2589

def digest_test_seed(digest)
  if @framework == "rspec"
    digest.update("seed\0#{MinitestIntegration::PINNED_SEED}\0#{ENV['SPEC_OPTS']}\0")
    %w[.rspec .rspec-local].each do |name|
      path = File.join(@project_root, name)
      digest.update("rspec-opts\0#{name}\0")
      digest.update(File.file?(path) ? File.binread(path) : "")
      digest.update("\0")
    end
  else
    digest.update("seed\0#{MinitestIntegration.seed}\0")
  end
end

#discard_load_counts_expression ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby that drops the line and method counts recorded while the sources loaded, and leaves Coverage running for the test (#426). The same call the fork capture uses before a test. The load snapshot in _load is already a copy, so this does not erase #load_lines.

Returns:

  • (String) —

    one statement for a capture subprocess script.



1905
1906
1907
# File 'lib/mutineer/coverage_map.rb', line 1905

def discard_load_counts_expression
  "Coverage.result(clear: true, stop: false)"
end

#drop_test(rel) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Removes rel from every map entry and forgets its timing.

Parameters:

  • rel (String) —

    project-relative test path.



2193
2194
2195
2196
2197
# File 'lib/mutineer/coverage_map.rb', line 2193

def drop_test(rel)
  @map.each_value { |tests| tests.delete(rel) if tests.is_a?(Array) }
  @map.delete_if { |_key, tests| !tests.is_a?(Array) || tests.empty? }
  @timings.delete(rel)
end

#each_covered_key(coverage) {|key| ... } ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Yields a "file:line" key for every project line with a non-zero count.

Parameters:

  • coverage (Hash) —

    counts per absolute file: an Array, or a Hash with "lines".

Yield Parameters:

  • key (String) —

    the "file:line" key.



1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
# File 'lib/mutineer/coverage_map.rb', line 1937

def each_covered_key(coverage)
  coverage.each do |abs_file, data|
    rel = relativize(abs_file)
    next if rel.start_with?("/") # outside project_root: not our source

    counts = data.is_a?(Hash) ? data["lines"] : data
    next unless counts.is_a?(Array) # a Coverage mode without line counts

    counts.each_with_index { |count, idx| yield "#{rel}:#{idx + 1}" if count&.positive? }
  end
end

#each_def(node) {|node| ... } ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Yields each def in node, including defs nested in another body.

Parameters:

  • node (Prism::Node, nil) —

    syntax node.

Yield Parameters:

  • node (Prism::DefNode)


2432
2433
2434
2435
2436
2437
# File 'lib/mutineer/coverage_map.rb', line 2432

def each_def(node, &block)
  return unless node.is_a?(Prism::Node)

  block.call(node) if node.is_a?(Prism::DefNode)
  node.child_nodes.each { |child| each_def(child, &block) }
end

#exact_failed_test?(source_rel) ⇒ Boolean (private)

True when a failed exact _test / _spec / test_ file pairs with this source. An app/ or lib/ source only accepts a test/ or spec/ file from its mirrored directory, so test/foo/bar_upsert_test.rb does not taint app/other/bar_upsert.rb. A concern also accepts the same names at its namespace path, but only when it has no test at its concerns/ path, as in Pairing.infer_tests. Any other source still matches by basename. A fixture under test/fixtures/ and an explicit test both name their source that way.

Parameters:

  • source_rel (String) —

    project-relative source path.

Returns:

  • (Boolean)


328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
# File 'lib/mutineer/coverage_map.rb', line 328

def exact_failed_test?(source_rel)
  name = File.basename(source_rel, ".rb")
  base, lib = Pairing.logical_path(source_rel)
  ns = Pairing.namespace_base(source_rel)
  ns = nil if ns && own_concern_test?(source_rel, ns)
  @failed_test_files.any? do |test_path|
    next false unless failed_test_target_name(test_path) == name

    rel = relativize(test_path)
    dir = File.dirname(rel)
    if app_or_lib_source?(source_rel) && conventional_test_dir?(dir)
      mirrored_test_dir?(rel, base, lib) || spec_mirror?(rel, base, lib) ||
        namespace_mirror?(rel, ns)
    else
      true
    end
  end
end

#fail_test(test_path, reason) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Records a failed coverage capture.

Parameters:

  • test_path (String) —

    test file path.

  • reason (String) —

    failure reason.



892
893
894
895
896
897
898
# File 'lib/mutineer/coverage_map.rb', line 892

def fail_test(test_path, reason)
  rel = relativize(test_path)
  @failed_test_files << rel
  # The reason can quote an app error, and so a credentialed DATABASE_URL.
  warn "[mutineer] coverage skipped for #{rel}: #{Redaction.text(reason)}"
  nil
end

#failed_split_in?(base, lib, concern:) ⇒ Boolean (private)

True when one failed split file in the mirror of base pairs with it.

Parameters:

  • base (String) —

    logical source path without extension.

  • lib (Boolean) —

    whether the source originated from lib/.

  • concern (Boolean) —

    true for a concern's namespace mirror, so a longer concern file can own the name.

Returns:

  • (Boolean)


438
439
440
441
442
443
444
445
446
447
448
449
450
# File 'lib/mutineer/coverage_map.rb', line 438

def failed_split_in?(base, lib, concern:)
  name = File.basename(base)
  @failed_test_files.any? do |t|
    test_rel = relativize(t)
    entry = File.basename(test_rel)
    next false unless Pairing.split_entry?(entry, name)
    next false unless mirrored_test_dir?(test_rel, base, lib)
    next false if Pairing.claimed_by_longer_source?(@project_root, base, entry, File.dirname(test_rel))
    next false if concern && Pairing.claimed_by_longer_concern?(@project_root, base, entry)

    true
  end
end

#failed_test_blames?(source_rel) ⇒ Boolean (private)

True when a failed test file pairs with source_rel by convention. Exact _test / _spec / test_ names match by basename, as before. A split <name>_*_test.rb matches only in the mirrored test directory, and only when no longer source file owns that name (#87). The answer is kept for this map, so a later delete does not move the failure.

Parameters:

  • source_rel (String) —

    project-relative source path.

Returns:

  • (Boolean)


310
311
312
313
314
315
# File 'lib/mutineer/coverage_map.rb', line 310

def failed_test_blames?(source_rel)
  @blame_for ||= {}
  return @blame_for[source_rel] if @blame_for.key?(source_rel)

  @blame_for[source_rel] = exact_failed_test?(source_rel) || split_failed_test?(source_rel)
end

#failed_test_target_name(test_path) ⇒ String (private)

Basename a failed test file would pair with, before the directory check.

Parameters:

  • test_path (String)

Returns:

  • (String)


383
384
385
386
387
388
389
390
# File 'lib/mutineer/coverage_map.rb', line 383

def failed_test_target_name(test_path)
  name = File.basename(test_path, ".rb")
  case name
  when /_(test|spec)\z/ then name.sub(/_(test|spec)\z/, "")
  when "test_helper" then name
  else name.delete_prefix("test_")
  end
end

#file_fingerprint(abs) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Byte fingerprint of a file for cache dependency checks.

Parameters:

  • abs (String) —

    absolute path.

Returns:

  • (String) —

    hex digest.



2025
2026
2027
2028
# File 'lib/mutineer/coverage_map.rb', line 2025

def file_fingerprint(abs)
  content = File.binread(abs)
  Digest::SHA256.hexdigest("#{content.bytesize}\0#{content}")
end

#fork_capture(abs_test, abs_sources, after_fork) ⇒ Object (private)

Fork the booted parent, run one test under the inherited Coverage, and return its per-source counts hash, a String diagnostic on failure, or :timeout after @capture_timeout (see #await_child). Reuses the same fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.



789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
# File 'lib/mutineer/coverage_map.rb', line 789

def fork_capture(abs_test, abs_sources, after_fork)
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @capture_timeout
  rd, wr = IO.pipe
  # Marshal output is binary: an un-binmoded pipe can raise
  # Encoding::UndefinedConversionError on write, which the child's rescue then
  # swallows, losing the real error and yielding a bare "no result".
  rd.binmode
  wr.binmode
  parent = Process.pid
  pid = fork do
    rd.close
    Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier
    OrphanGuard.start(parent)
    payload =
      begin
        ChildStdout.silence
        # Fork-safety hook: the in-process path reconnects AR; the daemon
        # drops its protocol channel and routes to its worker DB. Nil =
        # no-op. Injected so this file needs neither Runner (Prism) nor Rails.
        after_fork&.call
        Coverage.result(clear: true, stop: false) # discard pre-test delta
        passed, report = run_clean_with_report([abs_test])
        # {file => {lines: [...], methods: {...}}}; reduce to the counts
        # array record() expects, keeping only our source files.
        wanted = abs_sources.map { |path| FsPath.read(path) }
        # Coverage keys are US-ASCII with invalid bytes under LC_ALL=C (#346).
        coverage = Coverage.result(stop: false)
                           .to_h { |f, v| [FsPath.read(f), v] }
                           .select { |f, _| wanted.include?(f) }
                           .transform_values { |v| v.is_a?(Hash) ? lines_with_called_defs(v) : v }
        { "passed" => passed, "coverage" => coverage,
          "failure_report" => passed ? nil : report,
          "loaded_files" => capture_loaded_files }
      rescue Exception => e # rubocop:disable Lint/RescueException
        # Stringify (an arbitrary Exception may not marshal); the parent
        # surfaces this under --verbose. A String marshals safely over the pipe.
        "#{e.class}: #{e.message}#{e.backtrace&.first ? " @ #{e.backtrace.first}" : ''}"
      end
    begin
      wr.write(Marshal.dump(payload))
    rescue StandardError # rubocop:disable Lint/SuppressedException
      # pipe gone; parent records "no result"
    ensure
      wr.close
      exit!(0) # skip at_exit so the parent suite's autorun never re-fires here
    end
  end
  wr.close
  # Marshal.load reads exactly one object, not until EOF: a process that the
  # test leaves running (even outside the group) can hold the pipe open.
  status, payload = await_child(pid, deadline) { read_marshal(rd) }
  return :timeout unless status

  # An empty pipe means the child died before writing (e.g. a hard crash,
  # OOM, or a signal from the test's own subprocess handling). Report HOW it
  # died (exit status / signal) as a diagnostic string so --verbose has
  # something actionable instead of a silent "no result".
  return "child wrote no result (#{describe_status(status)})" if payload.nil?

  payload
rescue StandardError => e
  "parent could not read capture result: #{e.class}: #{e.message}"
ensure
  [rd, wr].compact.each { |io| io.close unless io.closed? }
end

#fork_clean_pass?(abs_tests, after_fork, timeout: @capture_timeout) ⇒ Array(Boolean, String, Boolean) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Runs test files in a fork of the booted parent and returns whether they passed, with a capped failure report for a red suite (#360). Bounded by timeout so a hung child cannot block the CLI.

Parameters:

  • abs_tests (Array<String>) —

    absolute test file paths.

  • after_fork (Proc, nil) —

    boot-mode fork hook.

  • timeout (Numeric) (defaults to: @capture_timeout) —

    seconds before the child is killed.

Returns:

  • (Array(Boolean, String, Boolean)) —

    pass flag, failure report, and whether the deadline passed.



1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
# File 'lib/mutineer/coverage_map.rb', line 1250

def fork_clean_pass?(abs_tests, after_fork, timeout: @capture_timeout)
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
  rd, wr = IO.pipe
  rd.binmode
  wr.binmode
  parent = Process.pid
  pid = fork do
    rd.close
    Process.setpgid(0, 0) rescue nil # rubocop:disable Style/RescueModifier
    OrphanGuard.start(parent)
    begin
      ChildStdout.silence
      after_fork&.call
      Coverage.result(clear: true, stop: false) if Coverage.running?
      passed, report = run_clean_with_report(abs_tests)
      wr.write(Marshal.dump([passed, report]))
    rescue Exception => e # rubocop:disable Lint/RescueException
      wr.write(Marshal.dump([false, Redaction.describe(e)]))
    ensure
      wr.close
      exit!(0)
    end
  end
  wr.close
  status, payload = await_child(pid, deadline) { read_marshal(rd) }
  return [false, "", true] if status.nil?
  return [false, "", false] unless payload.is_a?(Array)

  passed, report = payload
  [passed == true, report.to_s, false]
rescue StandardError
  [false, "", false]
ensure
  [rd, wr].compact.each { |io| io.close unless io.closed? }
end

#key_source(key) ⇒ String (private)

The source path of a "file:line" or "file:line:column" key.

Parameters:

  • key (String) —

    a map, load line or load method key.

Returns:

  • (String)


703
# File 'lib/mutineer/coverage_map.rb', line 703

def key_source(key) = key.sub(/(?::\d+)+\z/, "")

#kill_group(pid, waiter) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

SIGKILLs capture child pid and its process group, then waits for waiter to reap the child. Falls back to the pid alone when the group does not exist yet.

Parameters:

  • pid (Integer) —

    child pid, also its process group id.

  • waiter (Thread) —

    the Process.detach thread for pid.



1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
# File 'lib/mutineer/coverage_map.rb', line 1320

def kill_group(pid, waiter)
  begin
    Process.kill(:KILL, -pid)
  rescue Errno::ESRCH, Errno::EPERM
    # No group yet: the child has not run setpgid. Never signal a reaped pid.
    if waiter.alive?
      Process.kill(:KILL, pid) rescue nil # rubocop:disable Style/RescueModifier
    end
  end
  waiter.join
end

#line_counts_by_rel(coverage) ⇒ Hash{String => Array} (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Line-count arrays from a coverage hash, keyed by project-relative path.

Parameters:

  • coverage (Hash) —

    counts per absolute file.

Returns:

  • (Hash{String => Array})


1705
1706
1707
1708
1709
1710
1711
1712
# File 'lib/mutineer/coverage_map.rb', line 1705

def line_counts_by_rel(coverage)
  coverage.each_with_object({}) do |(abs_file, data), out|
    counts = data.is_a?(Hash) ? (data["lines"] || data[:lines]) : data
    next unless counts.is_a?(Array)

    out[relativize(abs_file)] = counts
  end
end

#lines_with_called_defs(data) ⇒ Array? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One file's line counts, with the def line of each method the test called counted too (#209). A forked capture does not see the def lines run, since the boot defined the methods before the test. Standalone capture clears the load snapshot before the test, so it does not either. Ruby counts no line when an endless method runs, so without this its mutants would be no_coverage even when a test calls it. A line where more than one method starts is not counted: the map keys tests by line, so the test would also be credited with the methods it did not call.

Parameters:

  • data (Hash) —

    Coverage result for one file, with :lines and :methods, or the JSON shape from #test_coverage_assignment ("lines" and "methods" as [line, column, count] rows).

Returns:

  • (Array, nil) —

    line counts.



1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
# File 'lib/mutineer/coverage_map.rb', line 1839

def lines_with_called_defs(data)
  lines = data[:lines] || data["lines"]
  methods = data[:methods] || data["methods"]
  return lines unless lines && methods

  lines = lines.dup
  entries = method_call_entries(methods)
  starts = entries.map(&:first).tally
  entries.each do |line, count|
    lines[line - 1] = [lines[line - 1].to_i, count].max if count.positive? && starts[line] == 1
  end
  lines
end

#load_coverage_expression ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby source of the capture child's load-time coverage: Coverage.peek_result for the configured sources only, matched by real path (a Coverage key is the path as required), so the payload does not carry every loaded gem. Each entry has the shape #load_entry builds.

Returns:

  • (String) —

    expression to embed in a capture subprocess script.



1892
1893
1894
1895
1896
# File 'lib/mutineer/coverage_map.rb', line 1892

def load_coverage_expression
  "Coverage.peek_result.filter_map { |f, v| key = Mutineer::FsPath.read((File.realpath(f) rescue f)); " \
    "[key, { \"lines\" => v[:lines], \"methods\" => v[:methods].filter_map { |k, n| k[2, 2] if n.positive? } }] " \
    "if #{abs_source_paths.map { |path| FsPath.read(path) }.inspect}.include?(key) }.to_h"
end

#load_entry(lines, methods) ⇒ Hash{String => Array} (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

One file's load-time coverage in the shape #record_load reads: the line counts, and the [line, column] of each method called at least once. #load_coverage_expression builds the same shape in a capture child.

Parameters:

  • lines (Array, nil) —

    line counts.

  • methods (Hash, nil) —

    Coverage method counts, keyed by [owner, name, start_line, start_column, end_line, end_column].

Returns:

  • (Hash{String => Array})


1881
1882
1883
# File 'lib/mutineer/coverage_map.rb', line 1881

def load_entry(lines, methods)
  { "lines" => lines, "methods" => (methods || {}).filter_map { |key, count| key[2, 2] if count.positive? } }
end

#load_failure_rescue ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby source, for a subprocess script, that closes a begin around the project and test file loads. A load error then prints one redacted line (Ruby's own printer would show DATABASE_URL raw), and the child still exits 1, as it did when the error went uncaught. Under --verbose the redacted backtrace follows; otherwise a hint says how to get it.

Returns:

  • (String) —

    Ruby script text.



1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
# File 'lib/mutineer/coverage_map.rb', line 1427

def load_failure_rescue
  detail =
    if @verbose
      <<~RUBY.chomp
        (_e.backtrace || []).each { |_f| $stderr.puts("\t" + Mutineer::Redaction.text(_f)) }
        _cause = _e.cause
        while _cause
          $stderr.puts("[mutineer] caused by: " + Mutineer::Redaction.describe(_cause))
          _cause = _cause.cause
        end
      RUBY
    else
      '$stderr.puts("[mutineer] re-run with --verbose for the backtrace")'
    end
  <<~RUBY.chomp
    rescue ScriptError, StandardError => _e
      require #{REDACTION_PATH.inspect}
      $stderr.puts("[mutineer] load failed: " + Mutineer::Redaction.describe(_e))
      #{detail}
      exit 1
  RUBY
end

#load_line_pairs ⇒ Hash{String => Array<String>} (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The tests in this run that #credit_load_only_line? treats as paired, per source. An empty list means every test keeps the load-only lines.

Returns:

  • (Hash{String => Array<String>}) —

    project-relative source to sorted test paths.



1759
1760
1761
1762
1763
1764
1765
1766
# File 'lib/mutineer/coverage_map.rb', line 1759

def load_line_pairs
  @source_paths.filter_map do |source|
    rel = relativize(absolute(source))
    next if rel.start_with?("/")

    [rel, paired_tests_in_run(rel).sort]
  end.to_h
end

#load_line_pairs_match?(cached) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when cached recorded the same #load_line_pairs this run has now. A missing key is a map saved before the pairing decision was stored.

Parameters:

  • cached (Hash) —

    parsed coverage.json.

Returns:

  • (Boolean)


1774
1775
1776
1777
1778
1779
1780
1781
1782
# File 'lib/mutineer/coverage_map.rb', line 1774

def load_line_pairs_match?(cached)
  saved = cached[LOAD_LINE_PAIRS]
  return false unless saved.is_a?(Hash)

  current = load_line_pairs
  return false unless saved.keys.sort == current.keys.sort

  current.all? { |rel, tests| Array(saved[rel]).sort == tests }
end

#load_method_bodies_unchanged?(cached, changed_sources) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when every load-time method of changed_sources still has the body the cache recorded. A different body can change a value other tests read without those tests appearing in this source's map.

Parameters:

  • cached (Hash) —

    parsed coverage.json.

  • changed_sources (Array<String>) —

    project-relative source paths.

Returns:

  • (Boolean)


2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
# File 'lib/mutineer/coverage_map.rb', line 2447

def load_method_bodies_unchanged?(cached, changed_sources)
  stored = cached["load_method_bodies"]
  return false unless stored.is_a?(Hash)

  wanted = changed_sources.to_set
  stored.all? do |key, digest|
    next true unless wanted.include?(key_source(key))
    next false unless digest.is_a?(String)

    body_digest_at(key) == digest
  end
end

#load_mismatch(cached, sources) ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This run's sources whose load lines or load methods differ in the capture.

Parameters:

  • cached (Hash) —

    the parsed coverage.json.

  • sources (Set<String>) —

    project-relative source paths.

Returns:

  • (Array<String>) —

    the sources that differ, sorted.



686
687
688
689
690
# File 'lib/mutineer/coverage_map.rb', line 686

def load_mismatch(cached, sources)
  owned = ->(keys) { Array(keys).select { |key| sources.include?(key_source(key)) }.to_set }
  moved = (owned.(cached["load_lines"]) ^ owned.(@load_lines)) + (owned.(cached["load_methods"]) ^ owned.(@load_methods))
  moved.map { |key| key_source(key) }.uniq.sort
end

#load_record_changed?(cached, changed_sources) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when this boot's load lines or load methods for changed_sources differ from the cache. The method body then changed what ran at boot, so a kept test's coverage is not trusted.

Parameters:

  • cached (Hash) —

    parsed coverage.json.

  • changed_sources (Array<String>) —

    project-relative source paths.

Returns:

  • (Boolean)


2216
2217
2218
2219
2220
2221
2222
2223
# File 'lib/mutineer/coverage_map.rb', line 2216

def load_record_changed?(cached, changed_sources)
  wanted = changed_sources.to_set
  pick = lambda do |keys|
    Array(keys).select { |key| wanted.include?(key_source(key)) }.to_set
  end
  pick.call(@load_lines) != pick.call(cached["load_lines"]) ||
    pick.call(@load_methods) != pick.call(cached["load_methods"])
end

#load_sets_from(coverage) ⇒ Array(Set, Set), Array(nil, nil) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Line and method keys that ran at load in coverage, limited to this run's sources. [nil, nil] when coverage is not a snapshot.

Parameters:

  • coverage (Hash, nil) —

    counts per absolute file, as #record_load reads them.

Returns:

  • (Array(Set, Set), Array(nil, nil))


1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
# File 'lib/mutineer/coverage_map.rb', line 1810

def load_sets_from(coverage)
  return [nil, nil] unless coverage.is_a?(Hash)

  lines = Set.new
  methods = Set.new
  ours = coverage.select { |abs_file, _| source_rels.include?(relativize(abs_file)) }
  each_covered_key(ours) { |key| lines << key }
  ours.each do |abs_file, data|
    next unless data.is_a?(Hash) && data["methods"].is_a?(Array)

    data["methods"].each { |line, column| methods << "#{relativize(abs_file)}:#{line}:#{column}" }
  end
  [lines, methods]
end

#loaded_files_expression ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby source of the child-side $LOADED_FEATURES filter (project .rb files).

Returns:

  • (String) —

    expression to embed in a capture subprocess script.



1953
1954
1955
1956
1957
1958
1959
1960
1961
# File 'lib/mutineer/coverage_map.rb', line 1953

def loaded_files_expression
  root = FsPath.read(project_root_real)
  prefix = root.b
  prefix += "/".b unless prefix.end_with?("/".b)
  # Byte prefix: a UTF-8 root and a binary loaded path must not raise.
  # A raise here used to be rescued into an empty list, and an empty
  # dependency hash then matched a stale cache (#346).
  "begin; _root = #{prefix.inspect}; $LOADED_FEATURES.filter_map { |f| next unless f.b.end_with?(\".rb\".b); abs = (File.realpath(f) rescue next); Mutineer::FsPath.read(abs) if Mutineer::FsPath.bytes_start_with?(abs, _root) }; rescue StandardError; []; end"
end

#loaded_relative(abs) ⇒ String? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Path of abs relative to the real project root, or nil when outside it.

Parameters:

  • abs (String) —

    absolute realpath.

Returns:

  • (String, nil)


2011
2012
2013
2014
2015
2016
2017
2018
# File 'lib/mutineer/coverage_map.rb', line 2011

def loaded_relative(abs)
  root = FsPath.read(project_root_real)
  prefix = root.b
  prefix += "/".b unless prefix.end_with?("/".b)
  return unless FsPath.bytes_start_with?(abs, prefix)

  FsPath.bytes_delete_prefix(abs, prefix)
end

#map_coverage(coverage) ⇒ Hash (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Line counts for the map, with def lines of methods the test called filled in. A fork capture already did that and sends plain arrays.

Parameters:

  • coverage (Hash) —

    counts per absolute file.

Returns:

  • (Hash) —

    the same files, values reduced to line-count arrays.



1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
# File 'lib/mutineer/coverage_map.rb', line 1648

def map_coverage(coverage)
  coverage.to_h do |file, data|
    lines = if data.is_a?(Hash) && (data.key?(:methods) || data.key?("methods"))
              lines_with_called_defs(data)
            else
              data
            end
    [file, lines]
  end
end

#method_bodies(rel) ⇒ Hash{Array(Integer, Integer) => String}? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Method bodies in rel, keyed by the def line and column Coverage uses. Nil when the file does not parse.

Parameters:

  • rel (String) —

    project-relative source path.

Returns:

  • (Hash{Array(Integer, Integer) => String}, nil)


2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
# File 'lib/mutineer/coverage_map.rb', line 2489

def method_bodies(rel)
  @method_bodies ||= {}
  return @method_bodies[rel] if @method_bodies.key?(rel)

  abs = absolute(rel)
  return @method_bodies[rel] = nil unless File.file?(abs)

  source = File.binread(abs)
  result = Prism.parse(source)
  return @method_bodies[rel] = nil unless result.errors.empty?

  found = {}
  each_def(result.value) do |node|
    loc = node.body&.location
    text = if loc && loc.end_offset > loc.start_offset
             source.byteslice(loc.start_offset, loc.end_offset - loc.start_offset)
           else
             +""
           end
    found[[node.location.start_line, node.location.start_column]] = text
  end
  @method_bodies[rel] = found
rescue SystemCallError
  @method_bodies[rel] = nil
end

#method_call_entries(methods) ⇒ Array<Array(Integer, Integer)> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Start line and call count for each method in a Coverage method table. A Hash is the live Coverage result. An Array is the JSON shape [line, column, count] from #test_coverage_assignment.

Parameters:

  • methods (Hash, Array) —

    method counts.

Returns:

  • (Array<Array(Integer, Integer)>) —

    [start_line, count] pairs.



1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
# File 'lib/mutineer/coverage_map.rb', line 1860

def method_call_entries(methods)
  if methods.is_a?(Hash)
    methods.map { |key, count| [key[2], count.to_i] }
  else
    Array(methods).filter_map do |row|
      next unless row.is_a?(Array) && row.size >= 3 && row[0].is_a?(Integer) && row[2].is_a?(Numeric)

      [row[0], row[2].to_i]
    end
  end
end

#method_ran_at_load?(file, line, column) ⇒ Boolean

True when the method whose def starts at line and column of file was called while the app booted or the sources loaded (see #load_methods).

Parameters:

  • file (String) —

    source file path.

  • line (Integer) —

    1-based line of the def.

  • column (Integer) —

    0-based byte column of the def.

Returns:

  • (Boolean)


246
247
248
# File 'lib/mutineer/coverage_map.rb', line 246

def method_ran_at_load?(file, line, column)
  @load_methods.include?("#{relativize(file)}:#{line}:#{column}")
end

#method_uncapturable?(file, line_range) ⇒ Boolean

Per-method taint. A mutant on a line whose enclosing method got zero successful coverage, in a file a failed sibling test targets, is :uncapturable (the capture that would have covered it errored), NOT a genuine gap. A method with any covered line means its uncovered lines are a real :no_coverage. A failed capture emits no coverage, so per-line intent is unknowable; method-range + successful coverage is the finest derivable signal. Fully-failed files behave exactly as uncapturable_source? did (every method range has zero coverage).

Parameters:

  • file (String) —

    source file path.

  • line_range (Range) —

    1-based enclosing-method line range.

Returns:

  • (Boolean)


286
287
288
289
290
291
292
293
# File 'lib/mutineer/coverage_map.rb', line 286

def method_uncapturable?(file, line_range)
  return false if @failed_test_files.empty?

  rel = relativize(absolute(file))
  return false unless failed_test_blames?(rel)

  line_range.none? { |ln| @map.key?("#{rel}:#{ln}") }
end

#minitest_clean_check_script(test_paths) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Minitest clean-suite check. Preloads configured sources and --require files like capture and standalone Runner.execute, so tests that rely on that preload stay green.

Parameters:

  • test_paths (Array<String>) —

    test file paths.

Returns:

  • (String) —

    Ruby script text.



1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
# File 'lib/mutineer/coverage_map.rb', line 1348

def minitest_clean_check_script(test_paths)
  <<~RUBY
    #{result_channel_expression}
    require "json"
    require #{FsPath::PATH.inspect}
    require "minitest"
    require "stringio"
    Mutineer::FsPath.install_minitest_path_filter!
    def Minitest.autorun; end
    _report = StringIO.new
    Minitest.define_singleton_method(:plugin_mutineer_report_init) { |options| reporter << Minitest::SummaryReporter.new(_report, options) }
    Minitest.extensions << "mutineer_report"
    $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
    begin
      #{abs_preload_paths.map { |path| FsPath.filesystem(path) }.inspect}.each { |f| require f }
      Minitest::Runnable.reset
      #{minitest_file_order_setup(Array(test_paths).map { |t| FsPath.filesystem(absolute(t)).inspect }.join(", "))}
    #{load_failure_rescue}
    end
    _passed = Minitest.run(#{minitest_seed_args_expression})
    _failure = _passed ? nil : #{redacted_expression("_report.string")}
    _result.puts JSON.generate("passed" => _passed == true, "failure_report" => _failure)
    _result.close
    exit(_passed ? 0 : 1)
  RUBY
end

#minitest_file_order_setup(files_list_source) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Loads the test files and installs MinitestIntegration::FileOrder so the subprocess clean check and coverage capture shuffle each file the same way as MinitestIntegration.run (#282). The child requires only the file-order file, not the rest of the runner.

Parameters:

  • files_list_source (String) —

    Ruby source for the path arguments, one inspected string or several joined by commas.

Returns:

  • (String) —

    Ruby script text.



1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
# File 'lib/mutineer/coverage_map.rb', line 1519

def minitest_file_order_setup(files_list_source)
  path = File.expand_path("minitest_integration/file_order.rb", __dir__)
  <<~RUBY.chomp
    _rank = {}
    [#{files_list_source}].each_with_index do |_f, _i|
      load _f
      Minitest::Runnable.runnables.each { |_klass| _rank[_klass] ||= _i }
    end
    require #{path.inspect}
    Mutineer::MinitestIntegration.keep_file_order(_rank)
  RUBY
end

#minitest_seed_args_expression ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Selects the seed inside the generated child, after its tests and helpers load. Choosing in the parent can ignore a helper's SEED assignment and let a clean check pass in an order the mutant run never uses (#282). The default comes from the same constant as the in-process runner; the child needs no Mutineer require and the parent's environment is unchanged.

Returns:

  • (String) —

    Ruby expression for the Minitest argument array.



1506
1507
1508
# File 'lib/mutineer/coverage_map.rb', line 1506

def minitest_seed_args_expression
  "ENV[\"SEED\"] ? [] : [\"--seed\", #{MinitestIntegration::PINNED_SEED.to_s.inspect}]"
end

#minitest_subprocess_script(test_path) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds the minitest subprocess script.

Parameters:

  • test_path (String) —

    test file path.

Returns:

  • (String) —

    Ruby script text.



1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
# File 'lib/mutineer/coverage_map.rb', line 1464

def minitest_subprocess_script(test_path)
  <<~RUBY
    #{result_channel_expression}
    require "coverage"
    require "json"
    require #{FsPath::PATH.inspect}
    require "minitest"
    require "stringio"
    Mutineer::FsPath.install_minitest_path_filter!
    def Minitest.autorun; end
    _report = StringIO.new
    Minitest.define_singleton_method(:plugin_mutineer_report_init) { |options| reporter << Minitest::SummaryReporter.new(_report, options) }
    Minitest.extensions << "mutineer_report"
    Coverage.start(lines: true, methods: true)
    $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
    begin
      #{abs_preload_paths.map { |path| FsPath.filesystem(path) }.inspect}.each { |f| require f }
      _load = #{load_coverage_expression}
      #{discard_load_counts_expression}
      Minitest::Runnable.reset
      #{minitest_file_order_setup(FsPath.filesystem(absolute(test_path)).inspect)}
    #{load_failure_rescue}
    end
    _passed = Minitest.run(#{minitest_seed_args_expression})
    _failure = _passed ? nil : #{redacted_expression("_report.string")}
    #{test_coverage_assignment}
    _result.puts JSON.generate("passed" => _passed == true, "coverage" => _coverage,
                                "failure_report" => _failure,
                                "load_coverage" => _load,
                                "loaded_files" => #{loaded_files_expression})
    _result.close
  RUBY
end

#mirrored_test_dir?(test_rel, base, lib) ⇒ Boolean (private)

True when test_rel sits in a mirrored test directory for base.

Parameters:

  • test_rel (String) —

    project-relative test path.

  • base (String) —

    logical source path without extension.

  • lib (Boolean) —

    whether the source originated from lib/.

Returns:

  • (Boolean)


458
459
460
461
462
# File 'lib/mutineer/coverage_map.rb', line 458

def mirrored_test_dir?(test_rel, base, lib)
  dirs = [Pairing.mirror_dir("test", base)]
  dirs << Pairing.mirror_dir("test/lib", base) if lib
  dirs.include?(File.dirname(test_rel))
end

#namespace_mirror?(test_rel, ns_base) ⇒ Boolean (private)

True when test_rel sits in the namespace mirror of a concern. The check is path only. A test at the concerns path does not block it.

Parameters:

  • test_rel (String) —

    project-relative test path.

  • ns_base (String, nil) —

    namespace base from Pairing.namespace_base.

Returns:

  • (Boolean)


353
354
355
356
357
358
# File 'lib/mutineer/coverage_map.rb', line 353

def namespace_mirror?(test_rel, ns_base)
  return false unless ns_base

  dirs = [Pairing.mirror_dir("test", ns_base), Pairing.mirror_dir("spec", ns_base)]
  dirs.include?(File.dirname(test_rel))
end

#namespace_spec?(source_rel) ⇒ Boolean (private)

True when the concern's namespace pairing is one spec file. Split names do not join a spec, so a failed split must not mark it.

Parameters:

  • source_rel (String) —

    project-relative concern path.

Returns:

  • (Boolean)


427
428
429
# File 'lib/mutineer/coverage_map.rb', line 427

def namespace_spec?(source_rel)
  Pairing.infer_tests(source_rel, project_root: @project_root).any? { |t| t.end_with?("_spec.rb") }
end

#order_tests(file, tests) ⇒ Array<String>

The covering tests of a mutant in file, in the order a mutant run loads them (#203): the files Pairing.infer_tests pairs with file first, then the cheapest by #timings. A file with no timing comes after the timed ones, and the path breaks a tie, so the same cache gives the same order on every run. Costs compare in doubling buckets (log2(seconds - fastest + 1)), so files of close cost keep their path order when a rebuild measures them again. Taking off the fastest captured file's time removes the startup cost every standalone capture pays; a failed capture is timed again on each run, so it does not count. A run that stops at the first failure then reaches a fast killing test before a slow file uses up the timeout.

Parameters:

  • file (String) —

    the mutated source file path.

  • tests (Array<String>) —

    project-relative test paths from #tests_for.

Returns:

  • (Array<String>) —

    the same paths, reordered.



217
218
219
220
221
222
223
224
225
226
227
# File 'lib/mutineer/coverage_map.rb', line 217

def order_tests(file, tests)
  rel = relativize(absolute(file))
  @paired ||= {}
  paired = @paired[rel] ||= Pairing.infer_tests(rel, project_root: @project_root,
                                                     prefer: @framework || "minitest")
  base = @timings.except(*@failed_test_files).values.min || 0
  tests.sort_by do |t|
    cost = @timings[t]
    [paired.include?(t) ? 0 : 1, cost ? Math.log2(cost - base + 1).floor : Float::INFINITY, t]
  end
end

#own_concern_test?(source_rel, ns_base) ⇒ Boolean (private)

True when pairing finds a test for this concern at its concerns/ path, so a test at its namespace path is not paired with it.

Parameters:

  • source_rel (String) —

    project-relative concern path.

  • ns_base (String) —

    namespace base from Pairing.namespace_base.

Returns:

  • (Boolean)


366
367
368
369
# File 'lib/mutineer/coverage_map.rb', line 366

def own_concern_test?(source_rel, ns_base)
  Pairing.infer_tests(source_rel, project_root: @project_root)
         .any? { |t| !namespace_mirror?(t, ns_base) }
end

#owner_files(root, base, listings) ⇒ Array<String> (private)

Longer .rb files that can own a split name of base.

Parameters:

  • root (String) —

    expanded project root.

  • base (String) —

    logical source path without extension.

  • listings (Hash{String => Array<String>}) —

    directory children, filled once.

Returns:

  • (Array<String>) —

    project-relative paths.



2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
# File 'lib/mutineer/coverage_map.rb', line 2634

def owner_files(root, base, listings)
  name = File.basename(base)
  dir = File.dirname(base)
  folders = [dir == "." ? nil : dir]
  %w[app lib].each { |prefix| folders << (dir == "." ? prefix : File.join(prefix, dir)) }
  folders.uniq.flat_map do |folder|
    abs = folder ? File.join(root, folder) : root
    entries = listings.fetch(abs) do
      listings[abs] = File.directory?(abs) ? Dir.children(abs).map { |entry| FsPath.read(entry) } : []
    end
    entries.filter_map do |entry|
      next unless entry.end_with?(".rb")

      stem = entry.delete_suffix(".rb")
      next unless stem.start_with?("#{name}_") && stem.length > name.length

      folder ? File.join(folder, entry) : entry
    end
  end
end

#ownership_paths ⇒ Array<String> (private)

Longer source files that can take a split test from a configured source. Only their presence is digested. A content edit of a sibling does not change pairing, and it does not rebuild coverage. Each directory is listed once, even when many sources share it. A concern also digests longer files in its namespace directory, because those files can own a namespace split name (#408). A model does not digest a concern file: the model keeps a split file it already pairs with.

Returns:

  • (Array<String>) —

    project-relative paths, sorted.



2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
# File 'lib/mutineer/coverage_map.rb', line 2612

def ownership_paths
  root = File.expand_path(@project_root)
  listings = {}
  paths = @source_paths.flat_map do |source|
    rel = relativize(absolute(source))
    next [] if rel.start_with?("/")

    base, = Pairing.logical_path(rel)
    bases = [base]
    ns = Pairing.namespace_base(rel)
    bases << ns if ns
    bases.uniq.flat_map { |logical| owner_files(root, logical, listings) }
  end
  paths.uniq.sort
end

#paired_among(source_rel, test_rels) ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Conventional tests for source_rel that are in test_rels.

Parameters:

  • source_rel (String) —

    project-relative source path.

  • test_rels (Set<String>) —

    project-relative test paths.

Returns:

  • (Array<String>)


2292
2293
2294
2295
2296
# File 'lib/mutineer/coverage_map.rb', line 2292

def paired_among(source_rel, test_rels)
  Pairing.infer_tests(source_rel, project_root: @project_root, prefer: @framework || "minitest")
         .select { |path| test_rels.include?(path) }
         .sort
end

#paired_tests_in_run(rel_source) ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Conventional tests for rel_source that this run actually captures.

Parameters:

  • rel_source (String) —

    project-relative source path.

Returns:

  • (Array<String>) —

    project-relative test paths.



1732
1733
1734
1735
1736
1737
1738
1739
# File 'lib/mutineer/coverage_map.rb', line 1732

def paired_tests_in_run(rel_source)
  @paired_in_run ||= {}
  @paired_in_run[rel_source] ||= begin
    run = @test_paths.to_set { |path| relativize(path) }
    Pairing.infer_tests(rel_source, project_root: @project_root, prefer: @framework || "minitest")
           .select { |path| run.include?(path) }
  end
end

#pairing_sets_changed?(old_rels, new_rels) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when the conventional pair for any run source is a different set of tests than the cache was built with. Load-only lines would move.

Parameters:

  • old_rels (Array<String>) —

    project-relative tests in the cache.

  • new_rels (Array<String>) —

    project-relative tests in this run.

Returns:

  • (Boolean)


2280
2281
2282
2283
2284
# File 'lib/mutineer/coverage_map.rb', line 2280

def pairing_sets_changed?(old_rels, new_rels)
  old_set = old_rels.to_set
  new_set = new_rels.to_set
  source_rels.any? { |rel| paired_among(rel, old_set) != paired_among(rel, new_set) }
end

#parallel_workers_match?(cached) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when cached records the same PARALLEL_WORKERS value this process has now. Rails reads that variable inside parallelize and can run one test file in several workers. A missing key is a map saved before this value was stored. In-process runs and the daemon write this same file.

Parameters:

  • cached (Hash) —

    parsed coverage.json.

Returns:

  • (Boolean)


2549
2550
2551
# File 'lib/mutineer/coverage_map.rb', line 2549

def parallel_workers_match?(cached)
  cached.key?("parallel_workers") && cached["parallel_workers"] == ENV.fetch("PARALLEL_WORKERS", nil)
end

#partial_cache?(cached) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when cached has the keys PARTIAL_CACHE_KEYS names.

Parameters:

  • cached (Hash) —

    parsed coverage.json.

Returns:

  • (Boolean)


2070
2071
2072
# File 'lib/mutineer/coverage_map.rb', line 2070

def partial_cache?(cached)
  PARTIAL_CACHE_KEYS.all? { |key| cached.key?(key) }
end

#partial_load_diverged?(cached) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when a recaptured standalone test saw different load lines than the cache recorded. The body change reached load time.

Parameters:

  • cached (Hash) —

    parsed coverage.json.

Returns:

  • (Boolean)


2231
2232
2233
2234
2235
2236
# File 'lib/mutineer/coverage_map.rb', line 2231

def partial_load_diverged?(cached)
  return false unless @seen_load_lines

  @seen_load_lines != Set.new(Array(cached["load_lines"])) ||
    @seen_load_methods != Set.new(Array(cached["load_methods"]))
end

#partial_plan(cached) ⇒ Hash? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

How to recapture part of cached, or nil when the run must capture every test. Nil covers a class-body edit, a moved line, a load-time method whose body changed, a loaded file outside the run's sources, a run input, and a change to which tests pair with a source (#421).

Parameters:

  • cached (Hash, nil) —

    parsed coverage.json.

Returns:

  • (Hash, nil) —

    "removed", "recapture", and "changed_sources".



2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
# File 'lib/mutineer/coverage_map.rb', line 2102

def partial_plan(cached)
  return nil unless cached.is_a?(Hash) && partial_cache?(cached)
  return nil unless cached.key?("load_methods") && cached.key?("timings")
  return nil unless parallel_workers_match?(cached) && standalone_load_lines_current?(cached)
  return nil unless cached["run_inputs"] == run_inputs_digest
  return nil unless dependencies_match?(cached, except: source_rels.to_a)

  tests = cached["tests"]
  sources = cached["sources"]
  skeletons = cached["skeletons"]
  return nil unless tests.is_a?(Hash) && sources.is_a?(Hash) && skeletons.is_a?(Hash)

  current_tests = test_fingerprints
  current_sources = source_fingerprints
  current_skeletons = source_skeletons
  return nil unless current_sources.keys.sort == sources.keys.sort

  changed_sources = []
  current_sources.each do |rel, fingerprint|
    next if sources[rel] == fingerprint

    skeleton = current_skeletons[rel]
    return nil if skeleton.nil? || skeletons[rel] != skeleton

    changed_sources << rel
  end
  return nil unless load_method_bodies_unchanged?(cached, changed_sources)
  return nil if @boot_path && load_record_changed?(cached, changed_sources)

  old_rels = tests.keys
  new_rels = current_tests.keys
  return nil if pairing_sets_changed?(old_rels, new_rels)

  removed = old_rels - new_rels
  added = new_rels - old_rels
  edited = (new_rels & old_rels).select { |rel| tests[rel] != current_tests[rel] }
  failed = Array(cached["failed_test_files"]) & new_rels
  touching = tests_in_source_entries(cached["map"], changed_sources) & new_rels
  recapture = (added + edited + failed + touching).uniq
  # Keeping nothing is a full capture. It rebuilds load lines in one pass.
  return nil if removed.empty? && recapture.size == new_rels.size

  { "removed" => removed, "recapture" => recapture, "changed_sources" => changed_sources }
end

#project_root_real ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Canonical project root for loaded-feature matching (/var vs /private/var).

Returns:

  • (String) —

    realpath of the project root when it exists.



1967
# File 'lib/mutineer/coverage_map.rb', line 1967

def project_root_real = ProjectPath.root_real(@project_root)

#ran_at_load?(file, line) ⇒ Boolean

True when file:line ran while the app booted or the sources loaded (see #load_lines).

Parameters:

  • file (String) —

    source file path.

  • line (Integer) —

    1-based line.

Returns:

  • (Boolean)


235
236
237
# File 'lib/mutineer/coverage_map.rb', line 235

def ran_at_load?(file, line)
  @load_lines.include?("#{relativize(file)}:#{line}")
end

#read_cache ⇒ Hash? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reads the coverage cache.

Returns:

  • (Hash, nil) —

    cached payload.



2708
2709
2710
2711
2712
2713
2714
# File 'lib/mutineer/coverage_map.rb', line 2708

def read_cache
  return nil unless File.exist?(cache_path)

  JSON.parse(File.read(cache_path, encoding: "UTF-8"))
rescue JSON::ParserError
  nil # corrupt cache: rebuild from scratch
end

#read_marshal(io) ⇒ Object? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reads the one Marshal object a forked capture child writes, without waiting for end of file.

Parameters:

  • io (IO) —

    the parent end of the binary result pipe.

Returns:

  • (Object, nil) —

    the object, or nil when the child wrote none.



1184
1185
1186
1187
1188
# File 'lib/mutineer/coverage_map.rb', line 1184

def read_marshal(io)
  Marshal.load(io)
rescue EOFError
  nil
end

#read_result_line(io) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Reads the one result line a #spawn_script child writes to fd RESULT_FD. The line is JSON and may name a non-ASCII path. The pipe follows the locale, so under LC_ALL=C those bytes arrive tagged US-ASCII and JSON.parse raises. The bytes are UTF-8 (#346).

Parameters:

  • io (IO) —

    the parent end of the result pipe.

Returns:

  • (String) —

    the line, or "" at end of file.



1171
1172
1173
1174
1175
1176
# File 'lib/mutineer/coverage_map.rb', line 1171

def read_result_line(io)
  line = io.gets
  return "" unless line

  line.dup.force_encoding(Encoding::UTF_8)
end

#record(coverage, test_path) ⇒ Object (private)

Records every source line with a non-zero execution count as covered by this test file. The counts are lines that ran after the sources loaded. Coverage.result keys are absolute; relativize and drop any path outside the project (stdlib/gem files).



1606
1607
1608
1609
# File 'lib/mutineer/coverage_map.rb', line 1606

def record(coverage, test_path)
  rel_test = relativize(test_path)
  each_covered_key(coverage) { |key| add_covering_test(key, rel_test) }
end

#record_clean_timeout(rel, seconds) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Notes a clean check that hit its deadline. The run still stops, as for a red suite, but the message says it timed out.

Parameters:

  • rel (String) —

    project-relative test path, or "combined suite".

  • seconds (Numeric) —

    the deadline that passed.



1090
1091
1092
1093
# File 'lib/mutineer/coverage_map.rb', line 1090

def record_clean_timeout(rel, seconds)
  record_failed_clean(rel)
  @clean_timeouts[rel] = seconds
end

#record_failed_clean(rel, detail = nil) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Notes a red unmutated suite for JobPlan.abort_if_unclean! (issue #360).

Parameters:

  • rel (String) —

    project-relative test path, or "combined suite".

  • detail (String, nil) (defaults to: nil) —

    failing test names / first error, capped.



950
951
952
953
954
955
956
# File 'lib/mutineer/coverage_map.rb', line 950

def record_failed_clean(rel, detail = nil)
  @failed_clean_tests << rel unless @failed_clean_tests.include?(rel)
  text = detail.to_s.strip
  return if text.empty?

  @failed_clean_details[rel] = truncate_clean_detail(text)
end

#record_load(coverage) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Adds the configured source lines that ran at load to #load_lines, and the methods called at load to #load_methods. Lines of other files (tests, helpers, gems) are dropped.

Parameters:

  • coverage (Hash, nil) —

    counts per absolute file, as #record reads them; a Hash entry can also hold "methods", as #load_entry builds it.



1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
# File 'lib/mutineer/coverage_map.rb', line 1792

def record_load(coverage)
  lines, methods = load_sets_from(coverage)
  return if lines.nil?

  @load_lines.merge(lines)
  @load_methods.merge(methods)
  return unless @collect_load

  @seen_load_lines = lines
  @seen_load_methods = methods
end

#record_loaded(paths) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Fingerprints project-local support files from a capture payload.

Parameters:

  • paths (Array, nil) —

    absolute loaded-file paths.



1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
# File 'lib/mutineer/coverage_map.rb', line 1992

def record_loaded(paths)
  Array(paths).each do |raw|
    next unless raw.is_a?(String) && File.file?(raw)

    abs = File.realpath(raw)
    rel = loaded_relative(abs)
    next unless rel
    next unless rel.end_with?(".rb")
    next if rel.start_with?("vendor/bundle/") || rel.start_with?("node_modules/")

    @loaded_dependencies[rel] = file_fingerprint(abs)
  end
end

#record_paired_load_lines(load_coverage, test_coverage, test_path) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Credits test_path with source lines that ran only while the sources loaded, when this test is one that should keep them (#426).

Standalone capture preloads every source in every test's process, so those lines would otherwise put every --test file on the map and a cache hit would check them all. The lines stay in #load_lines either way. They stay on the map for a paired test in this run: under --strategy reload that test can kill a mutant on the line by checking a value the load built (#348, Catalog.price). When the run has no paired test, every test keeps the lines, so that kill is not dropped. A line the test also ran after load is already on the map.

Parameters:

  • load_coverage (Hash, nil) —

    the load snapshot from the child.

  • test_coverage (Hash) —

    the post-load coverage from the child.

  • test_path (String) —

    test file path.



1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
# File 'lib/mutineer/coverage_map.rb', line 1676

def record_paired_load_lines(load_coverage, test_coverage, test_path)
  return unless load_coverage.is_a?(Hash)

  rel_test = relativize(test_path)
  post = line_counts_by_rel(map_coverage(test_coverage))
  @source_rels ||= @source_paths.to_set { |path| relativize(absolute(path)) }
  load_coverage.each do |abs_file, data|
    rel = relativize(abs_file)
    next unless @source_rels.include?(rel)
    next unless credit_load_only_line?(rel, rel_test)

    counts = data.is_a?(Hash) ? data["lines"] : data
    next unless counts.is_a?(Array)

    post_counts = post[rel]
    counts.each_with_index do |count, idx|
      next unless count&.positive?
      next if post_counts&.[](idx)&.positive?

      add_covering_test("#{rel}:#{idx + 1}", rel_test)
    end
  end
end

#redacted_expression(expression) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby source, for a subprocess script, that loads the redaction module and returns the redacted value of expression.

Parameters:

  • expression (String) —

    Ruby source for the text to redact.

Returns:

  • (String) —

    Ruby script text.



1415
1416
1417
# File 'lib/mutineer/coverage_map.rb', line 1415

def redacted_expression(expression)
  "(require #{REDACTION_PATH.inspect}; Mutineer::Redaction.text(#{expression}))"
end

#refresh_dependency_fingerprints(rels) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Writes the current fingerprint of each rels entry over the cached one. Only a path the cache already lists is refreshed: a test file that no test loads is tracked by the "tests" fingerprints, as on a full capture.

Parameters:

  • rels (Array<String>) —

    project-relative paths.



2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
# File 'lib/mutineer/coverage_map.rb', line 2245

def refresh_dependency_fingerprints(rels)
  rels.each do |rel|
    next unless @loaded_dependencies.key?(rel)

    abs = absolute(rel)
    next unless File.file?(abs)

    @loaded_dependencies[rel] = file_fingerprint(abs)
  end
end

#relativize(path) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Relativizes a path against the project root (see ProjectPath.relative).

Parameters:

  • path (String) —

    path to relativize.

Returns:

  • (String) —

    relative path, or an absolute path when outside the root.



2772
# File 'lib/mutineer/coverage_map.rb', line 2772

def relativize(path) = ProjectPath.relative(path, @project_root)

#remaining(deadline) ⇒ Float (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Seconds left before deadline, never negative.

Parameters:

  • deadline (Float) —

    a CLOCK_MONOTONIC time.

Returns:

  • (Float)


1224
1225
1226
# File 'lib/mutineer/coverage_map.rb', line 1224

def remaining(deadline)
  [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
end

#result_channel_expression ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby source that opens the result channel in a #spawn_script child. The script runs it first, so no file that a test opens can take fd RESULT_FD. Close-on-exec keeps the fd out of the test's own subprocesses. Binary mode writes the JSON bytes as they are, so a non-ASCII path is not rejected by an ASCII locale (#346).

Returns:

  • (String) —

    Ruby script text.



1236
1237
1238
# File 'lib/mutineer/coverage_map.rb', line 1236

def result_channel_expression
  "_result = IO.new(#{RESULT_FD}, \"w\"); _result.binmode; _result.close_on_exec = true"
end

#retry_failed_captures(after_fork) ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Re-runs tests whose previous capture crashed. A fixed helper is invisible to the source/test digest when that capture never recorded loaded_files. A capture runs its test, so a red test lands in #failed_clean_tests here.

Parameters:

  • after_fork (Proc, nil) —

    boot-mode fork hook.

Returns:

  • (Array<String>) —

    the project-relative tests it captured again.



1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
# File 'lib/mutineer/coverage_map.rb', line 1016

def retry_failed_captures(after_fork)
  pending = @failed_test_files.dup
  return pending if pending.empty?

  @failed_test_files = []
  pending.each do |rel|
    test_path = @test_paths.find { |t| relativize(t) == rel } || rel
    capture_one(test_path, after_fork)
  end
  pending
end

#reuse_capture(after_fork) ⇒ Mutineer::CoverageMap (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Takes the map from the --coverage-from capture instead of capturing, keeping only this run's sources, then runs the tests clean. A mutant runs only the tests that cover its line, often one file alone, so each test that covers one of this run's sources runs alone, as on a cache hit: a test that fails alone here would otherwise kill every mutant it runs. Those tests then run together. The other tests never run with a mutant in this run, so they are not checked (#398).

Parameters:

  • after_fork (Proc, nil) —

    boot-mode fork hook.

Returns:

Raises:



584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
# File 'lib/mutineer/coverage_map.rb', line 584

def reuse_capture(after_fork)
  cached = accepted_capture
  sources = source_fingerprints.keys.to_set
  @map = cached["map"].select { |key, _| sources.include?(key_source(key)) }
  @timings = cached["timings"] || {}
  @failed_test_files = []
  @failed_clean_tests = []
  @failed_clean_details = {}
  @clean_timeouts = {}
  @loaded_dependencies = cached["dependencies"]
  checked = clean_check_test_paths
  verify_cached_clean(after_fork: after_fork, test_paths: checked)
  verify_combined_clean(after_fork: after_fork)
  warn_unchecked("--coverage-from", checked.size)
  save
  self
end

#rspec_clean_check_script(test_paths) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

RSpec clean-suite check. Preloads configured sources and --require files like capture.

Parameters:

  • test_paths (Array<String>) —

    spec file paths.

Returns:

  • (String) —

    Ruby script text.



1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
# File 'lib/mutineer/coverage_map.rb', line 1381

def rspec_clean_check_script(test_paths)
  specs = Array(test_paths).map { |t| absolute(t).inspect }.join(", ")
  <<~RUBY
    #{result_channel_expression}
    require "json"
    require "stringio"
    begin
      require "rspec/core"
    rescue LoadError
      exit 3
    end
    RSpec::Core::Runner.disable_autorun!
    #{rspec_seed_install}
    $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
    begin
      #{abs_preload_paths.inspect}.each { |f| require f }
    #{load_failure_rescue}
    end
    #{rspec_order_preamble(specs)}
    _sink = StringIO.new
    status = RSpec::Core::Runner.run(["--no-color", #{specs}], _sink, _sink)
    _failure = status.zero? ? nil : #{redacted_expression("_sink.string")}
    _result.puts JSON.generate("passed" => status.zero?, "failure_report" => _failure)
    _result.close
    exit(status.zero? ? 0 : 1)
  RUBY
end

#rspec_order_preamble(spec_list_source) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby source that keeps spec files in the order given, the same hook as TestRunners::RSpec.run. The seed watcher is installed earlier, before the preloads (#rspec_seed_install).

Parameters:

  • spec_list_source (String) —

    Ruby source for the spec path arguments.

Returns:

  • (String) —

    Ruby script text.



1552
1553
1554
1555
1556
1557
1558
# File 'lib/mutineer/coverage_map.rb', line 1552

def rspec_order_preamble(spec_list_source)
  runner = File.expand_path("test_runners/rspec.rb", __dir__)
  <<~RUBY.chomp
    require #{runner.inspect}
    Mutineer::TestRunners::RSpec.keep_file_order([#{spec_list_source}])
  RUBY
end

#rspec_seed_install ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Installs the RSpec seed watcher. The subprocess must do this before it loads --require files, so a config.seed= there is recorded (#282).

Returns:

  • (String) —

    Ruby script text.



1537
1538
1539
1540
1541
1542
1543
# File 'lib/mutineer/coverage_map.rb', line 1537

def rspec_seed_install
  seed = File.expand_path("test_runners/rspec_seed.rb", __dir__)
  <<~RUBY.chomp
    require #{seed.inspect}
    Mutineer::TestRunners::RSpecSeed.install!
  RUBY
end

#rspec_subprocess_script(test_path) ⇒ Object (private)

Same coverage-JSON contract as the minitest path, but driven by RSpec: require rspec/core lazily, require the sources under Coverage, then run the one spec via RSpec::Core::Runner. The JSON goes to the result channel (see #spawn_script), so spec output cannot corrupt it. A missing rspec makes the script exit non-zero -> capture() records a skipped (incomplete-map) test, with a hint.



1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
# File 'lib/mutineer/coverage_map.rb', line 1566

def rspec_subprocess_script(test_path)
  <<~RUBY
    #{result_channel_expression}
    require "coverage"
    require "json"
    require #{FsPath::PATH.inspect}
    require "stringio"
    begin
      require "rspec/core"
    rescue LoadError
      warn "[mutineer] framework 'rspec' requested but rspec is not available in the project"
      exit 3
    end
    RSpec::Core::Runner.disable_autorun!
    #{rspec_seed_install}
    Coverage.start(lines: true, methods: true)
    $LOAD_PATH.unshift(*#{abs_load_paths.inspect})
    begin
      #{abs_preload_paths.inspect}.each { |f| require f }
      _load = #{load_coverage_expression}
      #{discard_load_counts_expression}
    #{load_failure_rescue}
    end
    #{rspec_order_preamble(absolute(test_path).inspect)}
    _sink = StringIO.new
    _status = RSpec::Core::Runner.run(["--no-color", #{absolute(test_path).inspect}], _sink, _sink)
    _failure = _status.zero? ? nil : #{redacted_expression("_sink.string")}
    #{test_coverage_assignment}
    _result.puts JSON.generate("passed" => _status.zero?, "coverage" => _coverage,
                                "failure_report" => _failure,
                                "load_coverage" => _load,
                                "loaded_files" => #{loaded_files_expression})
    _result.close
  RUBY
end

#run_clean_with_report(abs_tests) ⇒ Array(Boolean, String) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Runs tests in the current (forked) process and returns pass plus the redacted reporter failure text when red (#360).

Parameters:

  • abs_tests (Array<String>) —

    absolute test file paths.

Returns:

  • (Array(Boolean, String))


1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
# File 'lib/mutineer/coverage_map.rb', line 1292

def run_clean_with_report(abs_tests)
  if @framework == "rspec"
    code = TestRunners.for(@framework).run(abs_tests)
    raw = TestRunners::RSpec.last_output.to_s
  else
    require "minitest"
    require "stringio"
    report = StringIO.new
    Minitest.define_singleton_method(:plugin_mutineer_clean_report_init) do |options|
      reporter << Minitest::SummaryReporter.new(report, options)
    end
    Minitest.extensions << "mutineer_clean_report" unless Minitest.extensions.include?("mutineer_clean_report")
    code = TestRunners.for(@framework).run(abs_tests)
    raw = report.string
  end
  # Forked children print this into SmokeCheckError; redact like the
  # subprocess JSON path so DATABASE_URL passwords never reach stderr.
  [code.zero?, code.zero? ? "" : Redaction.text(raw)]
end

#run_inputs_digest ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Digest of everything that forces a full capture except source and test contents (#421). The source list is included, so adding a source still captures every test: standalone capture loads every source.

Returns:

  • (String) —

    hex digest.



2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
# File 'lib/mutineer/coverage_map.rb', line 2320

def run_inputs_digest
  digest = Digest::SHA256.new
  source_rels.to_a.sort.each do |rel|
    digest.update("source\0")
    digest.update(rel)
    digest.update("\0")
  end
  @require_paths.each { |path| digest_group(digest, "require", [digest_path(path)]) }
  digest_group(digest, "boot", [digest_path(@boot_path)]) if @boot_path
  ownership_paths.each do |rel|
    digest.update("owner\0")
    digest.update(rel)
    digest.update("\0")
  end
  @load_paths.sort.each { |load_path| digest.update("loadpath\0#{load_path}\0") }
  digest.update("framework\0#{@framework}\0")
  digest_test_seed(digest)
  digest.hexdigest
end

#run_phase_a ⇒ Object (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Runs standalone coverage capture.



708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
# File 'lib/mutineer/coverage_map.rb', line 708

def run_phase_a
  @phase_a_ran = true
  @map = {}
  @load_lines = Set.new
  @load_methods = Set.new
  @timings = {}
  @failed_test_files = []
  @failed_clean_tests = []
  @failed_clean_details = {}
  @clean_timeouts = {}
  @loaded_dependencies = {}
  @paired_in_run = nil

  @test_paths.each do |test_path|
    payload = timed(test_path) { capture(test_path) }
    next unless payload

    accept_capture_payload(test_path, payload)
  end
end

#run_phase_a_via_fork(after_fork:) ⇒ Object (private)

Boot-mode capture. For each test file, fork the booted parent; the child resets its Coverage delta, runs that ONE test, and marshals back the raw per-source coverage counts. record() inverts them exactly as the subprocess path does. Serial fork (one test at a time): boot apps fork cheaply via COW and per-test isolation matters more than throughput here.



734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
# File 'lib/mutineer/coverage_map.rb', line 734

def run_phase_a_via_fork(after_fork:)
  @phase_a_ran = true
  @map = {}
  @timings = {}
  @failed_test_files = []
  @failed_clean_tests = []
  @failed_clean_details = {}
  @clean_timeouts = {}
  @loaded_dependencies = {}
  abs_sources = abs_source_paths

  @test_paths.each do |test_path|
    accept_fork_payload(test_path, timed(test_path) { fork_capture(absolute(test_path), abs_sources, after_fork) })
  end
end

#save ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Saves the coverage cache.



2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
# File 'lib/mutineer/coverage_map.rb', line 2720

def save
  return unless @failed_clean_tests.empty?

  FileUtils.mkdir_p(@cache_dir)
  data = { "digest" => @digest, "failed_test_files" => @failed_test_files,
           "dependencies" => @loaded_dependencies, "map" => @map,
           "load_lines" => @load_lines.to_a.sort, "load_methods" => @load_methods.to_a.sort,
           "timings" => @timings, "parallel_workers" => ENV.fetch("PARALLEL_WORKERS", nil),
           NARROW_LOAD_LINES => true, "run_inputs" => run_inputs_digest,
           "sources" => source_fingerprints, "skeletons" => source_skeletons,
           "tests" => test_fingerprints, "load_method_bodies" => current_load_method_bodies }
  data[LOAD_LINE_PAIRS] = load_line_pairs unless @boot_path
  if @boot_path
    data.merge!("inputs" => compute_digest(inputs_only: true), "sources" => source_fingerprints,
                "owners" => ownership_paths)
  end
  tmp = "#{cache_path}.tmp"
  File.write(tmp, JSON.generate(data))
  File.rename(tmp, cache_path) # atomic swap
end

#sort_map_entries ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Puts every map entry in @test_paths order, which is the order a full capture records tests.



2204
2205
2206
# File 'lib/mutineer/coverage_map.rb', line 2204

def sort_map_entries
  @map.each_value { |tests| tests.sort_by! { |test| test_index(test) } if tests.is_a?(Array) }
end

#source_fingerprints ⇒ Hash{String => String} (private)

Fingerprint of each source, by project-relative path.

Returns:

  • (Hash{String => String})


695
696
697
# File 'lib/mutineer/coverage_map.rb', line 695

def source_fingerprints
  @source_paths.to_h { |p| [relativize(absolute(p)), file_fingerprint(absolute(p))] }
end

#source_rels ⇒ Set<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Project-relative paths of this run's sources.

Returns:

  • (Set<String>)


2302
2303
2304
# File 'lib/mutineer/coverage_map.rb', line 2302

def source_rels
  @source_rels ||= @source_paths.to_set { |path| relativize(absolute(path)) }
end

#source_skeleton_digest(abs) ⇒ String? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Digest of abs with each method body blanked, plus the line of every def. Two files match when the edit is inside method bodies and no line moved. A comment outside a body, a class-body statement, and an added or removed line do not match.

Parameters:

  • abs (String) —

    absolute source path.

Returns:

  • (String, nil) —

    hex digest, or nil when the file cannot be parsed.



2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
# File 'lib/mutineer/coverage_map.rb', line 2357

def source_skeleton_digest(abs)
  source = File.binread(abs)
  result = Prism.parse(source)
  return nil unless result.errors.empty?

  ranges = []
  tuples = []
  each_def(result.value) do |node|
    loc = node.body&.location
    range = body_byte_range(node)
    ranges << range if range
    tuples << [node.location.start_line, node.location.start_column, loc&.start_line, loc&.end_line]
  end
  digest = Digest::SHA256.new
  digest.update(blank_method_bodies(source, ranges))
  tuples.sort.each do |tuple|
    digest.update("\0")
    digest.update(tuple.map { |part| part.nil? ? "-" : part.to_s }.join(":"))
  end
  digest.hexdigest
rescue SystemCallError
  nil
end

#source_skeletons ⇒ Hash{String => String, nil} (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Skeleton digest of each source, by project-relative path. Nil when the file does not parse: a partial recapture then does not run.

Returns:

  • (Hash{String => String, nil})


2345
2346
2347
# File 'lib/mutineer/coverage_map.rb', line 2345

def source_skeletons
  @source_paths.to_h { |path| [relativize(absolute(path)), source_skeleton_digest(absolute(path))] }
end

#spawn_script(script, result: true, timeout: @capture_timeout) ⇒ Array(Process::Status, String) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Runs script in a fresh ruby - that reads the script from stdin. The child's stdout goes to File::NULL, so test output never reaches the user or the result. With result: true, the child writes its result as one line to fd RESULT_FD, a pipe that only the script uses. The child's stderr is the parent's stderr, so warnings from the script reach the user. A wall clock of timeout bounds the whole call (see #await_child), so a hung test cannot wedge the run.

The parent reads one line, not until EOF: a process that a test leaves running can inherit fd RESULT_FD (a fork without exec keeps it despite close-on-exec) and hold the pipe open long after the child exits. A clean check reports only through its exit status, so it gets no pipe.

Parameters:

  • script (String) —

    Ruby script text.

  • result (Boolean) (defaults to: true) —

    whether to open the result pipe on fd RESULT_FD.

  • timeout (Numeric) (defaults to: @capture_timeout) —

    seconds before the child is killed.

Returns:

  • (Array(Process::Status, String)) —

    the exit status and the line the child wrote to fd RESULT_FD ("" without one); [nil, ""] after a timeout.



1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
# File 'lib/mutineer/coverage_map.rb', line 1142

def spawn_script(script, result: true, timeout: @capture_timeout)
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
  script_rd, script_wr = IO.pipe
  result_rd, result_wr = IO.pipe if result
  options = { in: script_rd, out: File::NULL, pgroup: true }
  options[RESULT_FD] = result_wr if result
  pid = Process.spawn(RbConfig.ruby, "-", **options)
  script_rd.close
  result_wr&.close
  begin
    script_wr.write(script)
  rescue Errno::EPIPE
    # The child exited before reading its script; await_child still reaps it.
  end
  script_wr.close
  status, out = await_child(pid, deadline) { read_result_line(result_rd) if result }
  [status, out.to_s]
ensure
  [script_rd, script_wr, result_rd, result_wr].compact.each { |io| io.close unless io.closed? }
end

#spec_mirror?(test_rel, base, lib) ⇒ Boolean (private)

True when test_rel sits in a mirrored spec directory for base. Split Minitest names stay in #mirrored_test_dir?. An exact _spec file uses this directory.

Parameters:

  • test_rel (String) —

    project-relative test path.

  • base (String) —

    logical source path without extension.

  • lib (Boolean) —

    whether the source originated from lib/.

Returns:

  • (Boolean)


472
473
474
475
476
# File 'lib/mutineer/coverage_map.rb', line 472

def spec_mirror?(test_rel, base, lib)
  dirs = [Pairing.mirror_dir("spec", base)]
  dirs << Pairing.mirror_dir("spec/lib", base) if lib
  dirs.include?(File.dirname(test_rel))
end

#split_failed_test?(source_rel) ⇒ Boolean (private)

True when a failed split test file pairs with this source. Directory and the longer-source check match Pairing, so a test outside the mirror, or one owned by user_session.rb, does not taint user.rb. A concern with no test at its concerns/ path also accepts a split name at its namespace path (#408). A longer concern owns that name only when it pairs with the file. A namespace spec leaves split names unpaired, so a failed split does not mark the concern.

Parameters:

  • source_rel (String) —

    project-relative source path.

Returns:

  • (Boolean)


410
411
412
413
414
415
416
417
418
419
420
# File 'lib/mutineer/coverage_map.rb', line 410

def split_failed_test?(source_rel)
  base, lib = Pairing.logical_path(source_rel)
  return true if failed_split_in?(base, lib, concern: false)

  ns = Pairing.namespace_base(source_rel)
  return false unless ns
  return false if own_concern_test?(source_rel, ns)
  return false if namespace_spec?(source_rel)

  failed_split_in?(ns, false, concern: true)
end

#split_method_key(key) ⇒ Array(String, Integer, Integer) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Source path, def line, and def column of a load-method key.

Parameters:

  • key (String) —

    a "file:line:column" key.

Returns:

  • (Array(String, Integer, Integer))


2520
2521
2522
2523
2524
# File 'lib/mutineer/coverage_map.rb', line 2520

def split_method_key(key)
  rel = key_source(key)
  line, column = key.delete_prefix("#{rel}:").split(":").map(&:to_i)
  [rel, line, column]
end

#standalone_load_lines_current?(cached) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when a standalone cache was built with the #426 load-line rule and the same paired tests would keep load-only lines now. Boot and daemon maps never credited those lines to tests.

Parameters:

  • cached (Hash) —

    parsed coverage.json.

Returns:

  • (Boolean)


1748
1749
1750
1751
1752
# File 'lib/mutineer/coverage_map.rb', line 1748

def standalone_load_lines_current?(cached)
  return true if @boot_path

  cached[NARROW_LOAD_LINES] == true && load_line_pairs_match?(cached)
end

#subprocess_clean_pass?(test_paths, timeout: @capture_timeout) ⇒ Array(Boolean, String, Boolean) (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Runs test files in a fresh interpreter and returns whether they passed. The child writes a one-line JSON result with an optional failure report (#360), so a leftover process cannot hold a stderr pipe open.

Parameters:

  • test_paths (Array<String>) —

    test file paths.

  • timeout (Numeric) (defaults to: @capture_timeout) —

    seconds before the child is killed.

Returns:

  • (Array(Boolean, String, Boolean)) —

    pass flag, capped failure report, and whether the deadline passed.



1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
# File 'lib/mutineer/coverage_map.rb', line 1104

def subprocess_clean_pass?(test_paths, timeout: @capture_timeout)
  status, line = spawn_script(clean_check_script(test_paths), result: true, timeout: timeout)
  return [false, "", true] if status.nil?

  data = begin
    JSON.parse(line.to_s)
  rescue JSON::ParserError
    nil
  end
  # Fail closed: a child that exits 0 without a valid result line must not
  # clear the clean check (mutation honesty).
  return [false, "", false] unless data.is_a?(Hash)

  # Require the process exit too: an `at_exit` hook can fail after the
  # child already wrote `passed: true` (#360 warm-cache clean check).
  [status.success? && data["passed"] == true, data["failure_report"].to_s, false]
end

#subprocess_script(test_path) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Builds the framework-specific subprocess script.

Parameters:

  • test_path (String) —

    test file path.

Returns:

  • (String) —

    Ruby script text.



1455
1456
1457
# File 'lib/mutineer/coverage_map.rb', line 1455

def subprocess_script(test_path)
  @framework == "rspec" ? rspec_subprocess_script(test_path) : minitest_subprocess_script(test_path)
end

#test_coverage_assignment ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Ruby that stores the test's post-load coverage in _coverage. Each file keeps its line counts and every method as [start_line, start_column, count], so #lines_with_called_defs can credit a def line the test called. A line that ran only while the sources loaded is absent, because #discard_load_counts_expression ran first. Coverage keys are US-ASCII with invalid bytes under LC_ALL=C, so each key is read back with FsPath.read (#346).

Returns:

  • (String) —

    statements for a capture subprocess script.



1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
# File 'lib/mutineer/coverage_map.rb', line 1919

def test_coverage_assignment
  <<~RUBY.chomp
    _raw = Coverage.result
    _coverage = _raw.to_h do |_f, _v|
      next [Mutineer::FsPath.read(_f), _v] unless _v.is_a?(Hash)

      [Mutineer::FsPath.read(_f),
       { "lines" => _v[:lines], "methods" => (_v[:methods] || {}).map { |_k, _n| [_k[2], _k[3], _n] } }]
    end
  RUBY
end

#test_fingerprints ⇒ Hash{String => String} (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Fingerprint of each test file, by project-relative path.

Returns:

  • (Hash{String => String})


2310
2311
2312
# File 'lib/mutineer/coverage_map.rb', line 2310

def test_fingerprints
  @test_paths.to_h { |path| [relativize(absolute(path)), file_fingerprint(absolute(path))] }
end

#test_index(rel) ⇒ Integer (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Position of rel in @test_paths. A path outside the run sorts last.

Parameters:

  • rel (String) —

    project-relative test path.

Returns:

  • (Integer)


1637
1638
1639
1640
# File 'lib/mutineer/coverage_map.rb', line 1637

def test_index(rel)
  @test_index ||= @test_paths.each_with_index.to_h { |path, index| [relativize(path), index] }
  @test_index.fetch(rel, @test_index.length)
end

#tests_for(file, line) ⇒ Object

Lookup: the test files that cover file:line, or [] when none do. Per-file granularity; upgrade to per-method when throughput warrants (requires Minitest method isolation + finer Coverage tracking).



198
199
200
# File 'lib/mutineer/coverage_map.rb', line 198

def tests_for(file, line)
  @map["#{relativize(file)}:#{line}"] || []
end

#tests_in_source_entries(map, source_rels) ⇒ Array<String> (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Tests in map entries whose source is one of source_rels.

Parameters:

  • map (Hash, nil) —

    a "file:line" => [test files] map.

  • source_rels (Array<String>) —

    project-relative source paths.

Returns:

  • (Array<String>) —

    project-relative test paths.



2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
# File 'lib/mutineer/coverage_map.rb', line 2262

def tests_in_source_entries(map, source_rels)
  return [] unless map.is_a?(Hash)

  wanted = source_rels.to_set
  map.each_with_object([]) do |(key, tests), list|
    next unless wanted.include?(key_source(key))

    Array(tests).each { |test| list << test if test.is_a?(String) && !list.include?(test) }
  end
end

#timed(test_path) ⇒ Object (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Runs the block, a capture of test_path, and records its wall-clock seconds in #timings. The parent times the whole capture, so the numbers compare files, not exact test cost.

Parameters:

  • test_path (String) —

    test file path.

Yield Returns:

  • (Object) —

    the capture result.

Returns:

  • (Object) —

    the block's value.



758
759
760
761
762
763
# File 'lib/mutineer/coverage_map.rb', line 758

def timed(test_path)
  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  value = yield
  @timings[relativize(test_path)] = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(3)
  value
end

#truncate_clean_detail(text) ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Keeps the first failure block of a clean-failure report within CLEAN_FAILURE_DETAIL_LIMIT characters. RSpec progress dots can fill the head of the sink; prefer RSpec's Failures: / load-error header or Minitest's numbered N) Failure: / N) Error: line. Do not match a bare Error: — that cuts RSpec's Failure/Error: mid-token (#360).

Parameters:

  • text (String) —

    redacted reporter output.

Returns:

  • (String)


967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
# File 'lib/mutineer/coverage_map.rb', line 967

def truncate_clean_detail(text)
  starts = [text.index("Failures:")]
  # RSpec load errors and after(:suite)/after(:context) errors share this
  # header; do not require "while loading" or progress dots fill the cap.
  if (match = text.match(/^An error occurred /m))
    starts << match.begin(0)
  end
  if (match = text.match(/^\s*\d+\) (?:Failure|Error):/m))
    starts << match.begin(0)
  end
  start = starts.compact.min || 0
  report = start.zero? ? text : text[start..]
  return report if report.length <= CLEAN_FAILURE_DETAIL_LIMIT

  "#{report[0, CLEAN_FAILURE_DETAIL_LIMIT].rstrip}\n…"
end

#uncapturable_source?(file) ⇒ Boolean

Is this source file's empty coverage the result of an errored capture rather than a genuine coverage gap? True iff some capture failed this run AND this file got zero coverage from any successful capture AND a failed test file maps to it by the _test/spec/test naming convention. Derived from already-persisted state (@map keys + @failed_test_files). A split name checks the longer source files that existed when that check first ran for this map. Adding or deleting one of those files changes the coverage digest, so the next run captures again instead of retargeting a stored failure.

File-level, convention-based attribution. A line covered only by a failed test in an otherwise-covered file stays no_coverage (condition 2), and a source with no naming-convention test match is never tainted. Upgrade path: persist per-file coverage per successful run and diff against the failed set, or record test->source targets explicitly.

Returns:

  • (Boolean)


265
266
267
268
269
270
271
272
# File 'lib/mutineer/coverage_map.rb', line 265

def uncapturable_source?(file)
  return false if @failed_test_files.empty?

  rel = relativize(absolute(file))
  return false if covered_source_files.include?(rel)

  failed_test_blames?(rel)
end

#verify_cached_clean(after_fork: nil, test_paths: @test_paths) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Re-runs each successfully captured test on a cache hit. Digest equality cannot prove the current unmutated suite still passes.

Parameters:

  • after_fork (Proc, nil) (defaults to: nil) —

    boot-mode fork hook.

  • test_paths (Array<String>) (defaults to: @test_paths) —

    the tests to run, each alone.



991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
# File 'lib/mutineer/coverage_map.rb', line 991

def verify_cached_clean(after_fork: nil, test_paths: @test_paths)
  test_paths.each do |test_path|
    rel = relativize(test_path)
    next if @failed_test_files.include?(rel)

    ok, detail, timed_out = if @boot_path
                              fork_clean_pass?([absolute(test_path)], after_fork)
                            else
                              subprocess_clean_pass?([test_path])
                            end
    if timed_out
      record_clean_timeout(rel, @capture_timeout)
    elsif !ok
      record_failed_clean(rel, detail)
    end
  end
end

#verify_combined_clean(after_fork: nil) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Runs every successfully captured test of #clean_check_test_paths together. Per-file capture can miss a failure that only appears when covering files share one process.

Parameters:

  • after_fork (Proc, nil) (defaults to: nil) —

    boot-mode fork hook.



1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
# File 'lib/mutineer/coverage_map.rb', line 1052

def verify_combined_clean(after_fork: nil)
  runnable = clean_check_test_paths.reject { |t| @failed_test_files.include?(relativize(t)) }
  return if runnable.size < 2
  return unless @failed_clean_tests.empty?

  timeout = combined_clean_timeout(runnable)
  ok, detail, timed_out = if @boot_path
                            fork_clean_pass?(runnable.map { |t| absolute(t) }, after_fork, timeout: timeout)
                          else
                            subprocess_clean_pass?(runnable, timeout: timeout)
                          end
  if timed_out
    record_clean_timeout("combined suite", timeout)
  elsif !ok
    record_failed_clean("combined suite", detail)
  end
end

#warn_external_sources ⇒ Object (private)

A configured source that resolves outside project_root would silently be dropped (its coverage relativizes to an absolute path). Warn instead.



2689
2690
2691
2692
2693
2694
2695
2696
# File 'lib/mutineer/coverage_map.rb', line 2689

def warn_external_sources
  @source_paths.each do |p|
    next unless relativize(absolute(p)).start_with?("/")

    warn "[mutineer] source #{p} is outside project root #{@project_root}; " \
         "its coverage will be ignored"
  end
end

#warn_incomplete ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Warns when coverage capture was incomplete.



2745
2746
2747
2748
# File 'lib/mutineer/coverage_map.rb', line 2745

def warn_incomplete
  warn "[mutineer] cached coverage map may be incomplete; these test files " \
       "failed to contribute: #{@failed_test_files.join(', ')}"
end

#warn_recaptured(recaptured, total) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Tells the user how many test files a partial recapture ran again. Prints nothing when every file was recaptured or none was: the first is a full capture, and the second kept the whole map.

Parameters:

  • recaptured (Integer) —

    test files captured again.

  • total (Integer) —

    test files in the run.



2534
2535
2536
2537
2538
2539
# File 'lib/mutineer/coverage_map.rb', line 2534

def warn_recaptured(recaptured, total)
  kept = total - recaptured
  return unless recaptured.positive? && kept.positive?

  warn "[mutineer] coverage cache: recaptured #{recaptured} of #{total} test files; kept #{kept}."
end

#warn_unchecked(label, checked, miss: false) ⇒ void (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Tells the user on stderr how many test files the clean check left out (#398). Prints nothing when it left out none.

Parameters:

  • label (String) —

    what the run did: "coverage cache hit", "--coverage-from" or "coverage capture".

  • checked (Integer) —

    the number of test files in #clean_check_test_paths.

  • miss (Boolean) (defaults to: false) —

    true after a fresh capture, which ran every test alone, so only the together check leaves files out.



556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
# File 'lib/mutineer/coverage_map.rb', line 556

def warn_unchecked(label, checked, miss: false)
  others = @test_paths.size - checked
  return unless others.positive?

  one = others == 1
  covering = checked == 1 ? "1 test file that covers" : "#{checked} test files that cover"
  head, tail =
    if miss
      ["the together check covers only the #{covering}", "ran alone only"]
    else
      ["the clean check ran the #{covering}",
       "never #{one ? 'runs' : 'run'} with a mutant and #{one ? 'was' : 'were'} not checked"]
    end
  warn "[mutineer] #{label}: #{head} the sources; #{others} other #{one ? 'test file' : 'test files'} #{tail}."
end

#well_formed_capture?(cached) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when every entry the reuse reads has the type #save writes, so a hand-edited or foreign file is rejected with a reason, not a backtrace.

Parameters:

  • cached (Hash) —

    the parsed coverage.json.

Returns:

  • (Boolean)


671
672
673
674
675
676
677
678
# File 'lib/mutineer/coverage_map.rb', line 671

def well_formed_capture?(cached)
  strings = ->(value) { value.is_a?(Array) && value.all?(String) }
  cached["inputs"].is_a?(String) && strings.(cached["owners"]) &&
    cached["sources"].is_a?(Hash) && cached["sources"].all? { |k, v| k.is_a?(String) && v.is_a?(String) } &&
    cached["map"].all? { |k, v| k.is_a?(String) && strings.(v) } &&
    %w[load_lines load_methods].all? { |key| cached[key].nil? || strings.(cached[key]) } &&
    (cached["timings"].nil? || cached["timings"].is_a?(Hash))
end

#wrapped_capture?(payload) ⇒ Boolean (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

True when payload is the wrapped capture JSON/Marshal contract (passed + coverage), not a raw Coverage.result hash.

Parameters:

  • payload (Object) —

    parsed subprocess output or forked Marshal value.

Returns:

  • (Boolean)


906
907
908
# File 'lib/mutineer/coverage_map.rb', line 906

def wrapped_capture?(payload)
  payload.is_a?(Hash) && payload.key?("passed") && payload.key?("coverage")
end