kimera 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 558ffe918ec2624918506fb0616bd8426d8bb1a4c569abb4dd31e4ef9e74217d
-  data.tar.gz: 8ab25fa8b1f4c06085fb63606e20b1fb26691017d1bffc06c2d5dfa59b9e743c
+  metadata.gz: 05af564bc168e88e752fd28c2c623d8fe03b3d02402472819930015ceaff5492
+  data.tar.gz: 1708453bd3e4fb16b5eb054be04e94ff4ab8dc06a2c6297adc257c8e23d5fb9e
 SHA512:
-  metadata.gz: 889e8498b185c70c2e933954c2343729bfa8292a9651bd3b9f583080e85f9e7c212c4590c9d23388c6415798e81eff89620a598701ce2de1854956f806873434
-  data.tar.gz: bdd9bfab7f3409e107e52921bf6f210f0c25cf56a58b3afa6ebd01485ef1ea806fc5165b7fa732abd19bc1ec3eb59545d6055960f38ba6062c934891bfc9fa72
+  metadata.gz: 98620d29d7d69bdca3fc0bd51b51ee040e7a033627841e41e42860623cfd006d617805b817d428a2d688ca5df4c24ffde65aca0337985d7898ffae03b2f816c0
+  data.tar.gz: e509c0ff5416eb1cb41d8d933190d8e9d63249e010791e07ba5b0c0b0678d7e7d00aef6d2bee28dac103cfa4d8ffe6aea22b8515549b79a0bfe299f58df30d58

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.1.4 (2026-09-27)
+
+- Guard-style memoization is no longer mutated, just as `@x ||=` never was.
+  In a method that opens with `return @x if @x` (and assigns `@x` later) or
+  `return if @x` then `@x = true`, the guard gets no `condition` mutant and
+  the flag no `true => false`. Removing a memo only recomputes an equal value,
+  so those mutants always survived. A re-entrancy guard of the same shape is
+  skipped too.
+- `--isolated` first runs the unmutated suite once in a fresh mirror. If it
+  isn't green there (for example, a test helper that won't load), the run
+  stops with exit 1 and the error, as a red warm baseline does. Before, every
+  mutant it covered was scored `killed` with no failing test named.
+- An isolated mirror symlinks `vendor/`, `node_modules/` and `.bundle/`
+  instead of leaving them out. It creates `tmp/` and `log/` empty, and still
+  leaves out `.git/` and `coverage/`. A boot that needs frontend tooling or a
+  vendored bundle now loads in the mirror.
+- An isolated kill caused by a test file failing to load now puts the load
+  error (Minitest: message and first backtrace lines; RSpec: its load-error
+  report) in the result's `detail`.
+- Parallel warm workers follow Rails' fork contract more closely. Each sets
+  `ActiveSupport::TestCase.parallel_worker_id` to its slot, so per-worker
+  resources keyed on it (a Redis db, lease or key namespace, a port) no
+  longer collide between workers. `parallelize_before_fork` hooks run once per
+  fleet, not again before every spawn (including replacement workers forked
+  while other workers are mid-test). `parallelize_teardown` hooks get the
+  worker number.
+- A red parallel baseline lists, for each worker that ran a failing test,
+  where each failure fell in that worker's run and which tests ran just
+  before it. A test lost when its worker hit the hard timeout or crashed now
+  says so, instead of showing up as an unexplained failure.
+
 ## 0.1.3 (2026-09-27)
 
 - `--isolated` no longer scores a child that crashes before reporting results

data/README.md

@@ -234,6 +234,13 @@ SimpleCov.start { minimum_coverage(line: 100, branch: 100) unless ENV["KIMERA"]
 
 `kimera doctor` warns when it finds an ungated `minimum_coverage`.
 
+Each isolated mirror is a copy of the project root with some exceptions:
+`.git/` and `coverage/` are left out, `tmp/` and `log/` start empty, and
+`vendor/`, `node_modules/` and `.bundle/` are symlinked to the originals. The
+exception is a directory that holds a mutated file, which is always copied.
+Before judging any mutant, `--isolated` runs the unmutated suite once in a
+mirror. If it isn't green there, the run stops with exit 1 and the error.
+
 ### Progress output
 
 During a run, a progress bar tracks each phase on stderr. It shows only when
@@ -306,6 +313,13 @@ The *default* set is small and low-noise:
 - `!x => x`
 - forced `if` conditions
 
+Memoization is not a mutation target. Dropping a memo only recomputes an equal
+value, so that mutant would always survive. `@x ||= …` has no such mutant, and
+neither does a guard that opens a method: `return @x if defined?(@x)`,
+`return @x if @x` (with `@x` assigned later in the method), or `return if @x`
+followed by `@x = true`. Everything the method computes is still mutated. A
+re-entrancy guard with the run-once shape is skipped too.
+
 The extended families are one flag away. Use `--operators all`, or pick from:
 
 | family | mutation |

data/lib/kimera/cli/run/pass.rb

@@ -63,7 +63,7 @@ class Kimera::CLI::Run::Pass
   end
 
   def run(remaining)
-    isolated = ->(ids) { isolation.run(ids: ids, label: "mutants (isolated)") }
+    isolated = ->(ids) { judge(ids) }
     return isolated.call(remaining) if @options[:isolated]
     pooled(remaining, isolated)
   end
@@ -74,8 +74,13 @@ class Kimera::CLI::Run::Pass
     harness.run(ids: together, label: "mutants (warm)").merge(isolated.call(apart))
   end
 
+  def judge(ids)
+    isolation.verify!
+    isolation.run(ids: ids, label: "mutants (isolated)")
+  end
+
   def isolation
-    Kimera::Execution::IsolatedExecution.new(**core, **{ hard_timeout: @options[:hard_timeout] }.compact)
+    @_isolation ||= Kimera::Execution::IsolatedExecution.new(**core, **limits)
   end
 
   def core
@@ -84,6 +89,8 @@ class Kimera::CLI::Run::Pass
       .merge(framework: @options[:framework], test_files: files)
   end
 
+  def limits = { hard_timeout: @options[:hard_timeout] }.compact
+
   def split(ids)
     patterns = Array(@options[:isolate_when_covered_by])
     ids.partition do |id|

data/lib/kimera/execution/baseline_failure/breakdown.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class Kimera::Execution::BaselineFailure::Breakdown
+  MAX_FAILURES = 5
+  PRECEDING = 3
+
+  def initialize(failed, workers)
+    @failed = failed
+    @workers = workers
+  end
+
+  def to_s
+    lines = @workers.sort_by(&:first).filter_map { |slot, ids| worker(slot, ids) }
+    lines.empty? ? "" : "\n  per worker (tests in the order it ran them):\n#{lines.join("\n")}"
+  end
+
+  private
+
+  def worker(slot, ids)
+    hits = ids.each_index.select { |index| @failed.include?(ids[index]) }
+    return if hits.empty?
+    "    worker #{slot}: ran #{ids.size}; failed #{failures(ids, hits)}#{preceding(ids, hits.first)}"
+  end
+
+  def failures(ids, hits)
+    shown = hits.first(MAX_FAILURES).map { |index| "##{index + 1} #{ids[index]}" }
+    extra = hits.size - shown.size
+    shown.join(", ") + (extra.positive? ? " (+#{extra} more)" : "")
+  end
+
+  def preceding(ids, first)
+    before = ids[[first - PRECEDING, 0].max...first]
+    before.empty? ? " (first test on this worker)" : "; just before: #{before.join(", ")}"
+  end
+end

data/lib/kimera/execution/baseline_failure.rb

@@ -10,15 +10,27 @@ end
 class Kimera::Execution::BaselineFailure < Kimera::Error
   MAX_DETAILS = 3
   MAX_MESSAGE = 300
+  LOSSES = { timeout: "its worker was killed at the hard timeout (--hard-timeout) before reporting a result" }.freeze
+  CRASH = "its worker died before reporting a result"
 
   class << self
-    def build(failed, messages, command)
-      new(summary(failed, messages, command))
+    def build(failed, messages, command, workers: {})
+      new(summary(failed, messages, command, workers: workers))
     end
 
-    def summary(failed, messages, command)
+    def lost(reason) = LOSSES.fetch(reason, CRASH)
+
+    def mirrored(reason, hint)
+      new(
+        "isolated baseline is not green: the unmutated suite fails in a mirror of the project\n  " \
+          "#{reason.gsub("\n", "\n    ")}\n#{hint}"
+      )
+    end
+
+    def summary(failed, messages, command, workers: {})
       text = "baseline suite is not green: #{failed.join(", ")}"
       text += appendix(failed, messages)
+      text += Kimera::Execution::BaselineFailure::Breakdown.new(failed, workers).to_s
       "#{text}\n  reproduce without kimera: #{command}"
     end
 
@@ -41,3 +53,5 @@ class Kimera::Execution::BaselineFailure < Kimera::Error
     end
   end
 end
+
+require_relative "baseline_failure/breakdown"

data/lib/kimera/execution/baseline_pass.rb

@@ -71,7 +71,13 @@ class Kimera::Execution::BaselinePass
   end
 
   def dispatch
-    yield(resolve: resolve, lost: loss)
+    yield(resolve: resolve, lost: loss, trace: tracer)
+  end
+
+  def journal = @_journal ||= Hash.new { |workers, slot| workers[slot] = [] }
+
+  def tracer
+    ->(slot, test_id) { journal[slot] << test_id }
   end
 
   def resolve
@@ -90,7 +96,8 @@ class Kimera::Execution::BaselinePass
     method(:lost)
   end
 
-  def lost(test_id, _reason)
+  def lost(test_id, reason)
+    @messages[test_id] = Kimera::Execution::BaselineFailure.lost(reason)
     tally.failures << test_id
     @progress.tick
   end
@@ -119,6 +126,6 @@ class Kimera::Execution::BaselinePass
 
   def failure!(failed)
     command = @adapter.reproduce(failed.first(Kimera::Execution::BaselineFailure::MAX_DETAILS))
-    raise(Kimera::Execution::BaselineFailure.build(failed, @messages, command))
+    raise(Kimera::Execution::BaselineFailure.build(failed, @messages, command, workers: journal))
   end
 end

data/lib/kimera/execution/harness.rb

@@ -126,8 +126,8 @@ class Kimera::Execution::Harness
   end
 
   def parallel(pass)
-    pass.parallel! do |resolve:, lost:|
-      driver.drive(adapter.test_ids, driver.method(:channel), resolve: resolve, lost: lost)
+    pass.parallel! do |resolve:, lost:, trace:|
+      driver.drive(adapter.test_ids, driver.method(:channel), resolve: resolve, lost: lost, trace: trace)
     end
   end
 

data/lib/kimera/execution/isolated.rb

@@ -5,6 +5,7 @@ require "tmpdir"
 require_relative "../results/result"
 require_relative "../results/run_report"
 require_relative "../synthesis/overlay"
+require_relative "baseline_failure"
 require_relative "isolated_plan"
 require_relative "isolated_scheduling"
 require_relative "isolated_verdict"
@@ -30,6 +31,13 @@ class Kimera::Execution::IsolatedExecution
     @options = options
   end
 
+  def verify!
+    errors.puts("kimera: isolated baseline (unmutated mirror)") unless progress.enabled?
+    outcome = with_mirror { |mirror| verdict(mirror, plan.suite) }
+    return if outcome.status == :survived
+    raise(Kimera::Execution::BaselineFailure.mirrored(outcome.explain(limit), Kimera::Execution::IsolatedPlan::MIRROR_HINT))
+  end
+
   def run(ids: self.ids, label: "mutants")
     progress.start(ids.size, label)
     report(ids)

data/lib/kimera/execution/isolated_child.rb

@@ -9,7 +9,8 @@ begin
 rescue StandardError, ScriptError
   nil
 end
-RSpec.configuration.output_stream = StringIO.new
+output = StringIO.new
+RSpec.configuration.output_stream = output
 RSpec.configuration.error_stream = StringIO.new
 RSpec.configuration.deprecation_stream = StringIO.new
 
@@ -19,6 +20,8 @@ code = RSpec::Core::Runner.run(locations)
 
 failed = RSpec.world.all_examples.select { |example| example.execution_result.status == :failed }
 outside = RSpec.world.non_example_failure ? 1 : 0
-File.write(ledger, JSON.generate(failures: failed.size + outside, failing: failed.map(&:id)))
+report = { failures: failed.size + outside, failing: failed.map(&:id) }
+report[:load_error] = output.string.strip[0, 4000] if outside.positive?
+File.write(ledger, JSON.generate(report))
 
 exit code

data/lib/kimera/execution/isolated_child_minitest.rb

@@ -21,7 +21,8 @@ ARGV.clear
 begin
   files.each { |f| require File.expand_path(f) }
 rescue StandardError, ScriptError => error
-  File.write(ledger, JSON.generate(failures: 1, failing: [], load_error: "#{error.class}: #{error.message}"))
+  cause = ["#{error.class}: #{error.message}", *Array(error.backtrace).first(5).map { |line| "  #{line}" }]
+  File.write(ledger, JSON.generate(failures: 1, failing: [], load_error: cause.join("\n")))
   exit(1)
 end
 

data/lib/kimera/execution/isolated_outcome.rb

@@ -19,6 +19,13 @@ class Kimera::Execution::IsolatedOutcome
     @detail = detail
   end
 
+  def explain(limit)
+    return "timed out after #{limit}s" if status == :timeout
+    named = Array(failing)
+    return "failing: #{named.join(", ")}" if named.any?
+    detail || "the test child failed without naming a test"
+  end
+
   class << self
     def judge(exit, path, stderr = "")
       return new(:timeout) if exit == :timeout
@@ -50,7 +57,7 @@ class Kimera::Execution::IsolatedOutcome
 
     def tally(exit, ledger)
       failing = Array(ledger["failing"])
-      return new(:killed, failing) if ledger["failures"].positive?
+      return new(:killed, failing, ledger["load_error"]) if ledger["failures"].positive?
       return new(:survived) if exit.success?
       new(:harness_error, nil, unexplained(exit))
     end

data/lib/kimera/execution/isolated_plan.rb

@@ -10,7 +10,12 @@ module Kimera
 end
 
 class Kimera::Execution::IsolatedPlan
-  MIRROR_SKIP = %w[.git tmp vendor node_modules coverage log .bundle].freeze
+  MIRROR_SKIP = %w[.git coverage].freeze
+  MIRROR_EMPTY = %w[tmp log].freeze
+  MIRROR_LINK = %w[vendor node_modules .bundle].freeze
+  MIRROR_HINT =
+    "  the mirror copies the project except #{MIRROR_SKIP.join(", ")} " \
+      "(#{MIRROR_EMPTY.join(", ")} start empty; #{MIRROR_LINK.join(", ")} are symlinked)".freeze
 
   attr_reader :registry
 
@@ -34,14 +39,17 @@ class Kimera::Execution::IsolatedPlan
     child.command(mirror, locations, ledger: ledger, paths: mutables)
   end
 
+  def suite = selection.all
+
   def mutables
     @registry.files.map { |f| f.split(File::SEPARATOR).first }.uniq
   end
 
-  class << self
-    def mirrors(entries)
-      entries.reject { |entry| MIRROR_SKIP.include?(entry) }
-    end
+  def placement(entry)
+    return :copy if mutables.include?(entry)
+    return :skip if MIRROR_SKIP.include?(entry)
+    return :empty if MIRROR_EMPTY.include?(entry)
+    MIRROR_LINK.include?(entry) ? :link : :copy
   end
 
   private

data/lib/kimera/execution/isolated_verdict.rb

@@ -59,8 +59,14 @@ module Kimera
 
       def populate(mirror)
         root = plan.root
-        IsolatedPlan.mirrors(Dir.children(root)).each do |entry|
-          FileUtils.cp_r(File.join(root, entry), File.join(mirror, entry))
+        Dir.children(root).each { |entry| place(File.join(root, entry), File.join(mirror, entry), entry) }
+      end
+
+      def place(source, target, entry)
+        case plan.placement(entry)
+        when :copy then FileUtils.cp_r(source, target)
+        when :link then File.symlink(source, target)
+        when :empty then FileUtils.mkdir_p(target) if File.directory?(source)
         end
       end
 

data/lib/kimera/execution/parallel_test_databases.rb

@@ -19,23 +19,31 @@ class Kimera::Execution::ParallelTestDatabases
   end
 
   def after_fork(index)
+    identify(index)
     return unless index && active?
     ActiveSupport::Testing::Parallelization.after_fork_hooks.each { |hook| hook.call(index) }
     @adapter.start
   end
 
   def before_exit(index)
-    Array(index).each { cleanup }
+    Array(index).each { |worker| cleanup(worker) }
   rescue StandardError => error
     errors.puts("kimera: parallelize_teardown failed (#{error.class}: #{error.message})")
   end
 
   private
 
-  def cleanup
+  def cleanup(index)
     return unless active?
     scrub
-    ActiveSupport::Testing::Parallelization.run_cleanup_hooks.each(&:call)
+    ActiveSupport::Testing::Parallelization.run_cleanup_hooks.each { |hook| hook.call(index) }
+  end
+
+  def identify(index)
+    return unless index && @jobs > 1 && defined?(ActiveSupport::TestCase)
+    ActiveSupport::TestCase.parallel_worker_id = index
+  rescue NoMethodError
+    nil
   end
 
   def scrub

data/lib/kimera/execution/pool_driver.rb

@@ -46,10 +46,11 @@ class Kimera::Execution::Pool
     @options[:coverage] = measured
   end
 
-  def drive(queue, spawner, resolve:, lost:)
+  def drive(queue, spawner, resolve:, lost:, trace: nil)
+    database.before_fork
     Kimera::Execution::WorkerPool.new(
       queue: queue, spawner: spawner, jobs: @options.fetch(:jobs),
-      hard_timeout: @options.fetch(:hard), resolve: resolve, lost: lost
+      hard_timeout: @options.fetch(:hard), resolve: resolve, lost: lost, trace: trace
     ).run
   end
 
@@ -66,7 +67,6 @@ class Kimera::Execution::Pool
   def database = @options.fetch(:paralleldb)
 
   def launch(entry, index)
-    database.before_fork
     duty = Duty.new(entry, index, channels)
     [spawn(duty), *duty.pipes.parent!]
   end

data/lib/kimera/execution/worker_pool/worker.rb

@@ -10,6 +10,11 @@ Kimera::Execution::WorkerPool::Worker =
       self.inflight = id
     end
 
+    def claim(id, limit)
+      busy!(id)
+      renew(limit)
+    end
+
     def renew(limit)
       self.deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + limit
     end

data/lib/kimera/execution/worker_pool.rb

@@ -29,8 +29,8 @@ class Kimera::Execution::WorkerPool
   def assign(worker)
     id = fleet.take
     return close(worker) unless id
-    worker.busy!(id)
-    worker.renew(limit)
+    worker.claim(id, limit)
+    trace(worker.slot, id)
     worker.offer(id)
   end
 
@@ -83,6 +83,8 @@ class Kimera::Execution::WorkerPool
     worker.renew(limit)
   end
 
+  def trace(slot, id) = context.options[:trace]&.call(slot, id)
+
   def close(worker) = shut(worker.retire)
 
   def watch

data/lib/kimera/memo_guard.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "support/syntax"
+require_relative "support/syntax_types"
+
+class Kimera::MemoGuard
+  CONDITIONAL = "conditional"
+  BOOLEAN_LITERAL = "boolean_literal"
+  READ = Kimera::SyntaxTypes::InstanceVariableReadNode
+  WRITE = Kimera::SyntaxTypes::InstanceVariableWriteNode
+
+  Exemption = Data.define(:location, :operator)
+
+  class << self
+    def exemptions(source)
+      result = Kimera::Syntax.parse(source)
+      return [] if result.failure?
+      defs(result.value).flat_map { new(statements(it.body)).exemptions }
+    end
+
+    def statements(body) = body.is_a?(Kimera::SyntaxTypes::StatementsNode) ? body.body : []
+
+    def defs(node, found = [])
+      found << node if node.is_a?(Kimera::SyntaxTypes::DefNode)
+      node.compact_child_nodes.each { defs(it, found) }
+      found
+    end
+  end
+
+  def initialize(statements)
+    @guard, @flag, *@rest = statements
+  end
+
+  def exemptions
+    return [] unless name && (value? || flag?)
+    [Exemption.new(@guard.location, CONDITIONAL), *raised]
+  end
+
+  private
+
+  def name
+    predicate = @guard.predicate if guard?
+    predicate.name if predicate.is_a?(READ)
+  end
+
+  def guard? = @guard.is_a?(Kimera::SyntaxTypes::IfNode) && @guard.compact_child_nodes.size == 2 && returns?
+
+  def returns? = @guard.statements.body.size == 1 && returned.is_a?(Kimera::SyntaxTypes::ReturnNode)
+
+  def returned = @guard.statements.body.first
+
+  def value? = caches? && [@flag, *@rest].any? { named?(it, WRITE) }
+
+  def caches?
+    values = returned.arguments&.arguments
+    values&.size == 1 && named?(values.first, READ)
+  end
+
+  def flag? = returned.compact_child_nodes.empty? && raises?
+
+  def raises? = named?(@flag, WRITE) && @flag.value.is_a?(Kimera::SyntaxTypes::TrueNode)
+
+  def raised = flag? ? [Exemption.new(@flag.value.location, BOOLEAN_LITERAL)] : []
+
+  def named?(node, kind) = node.is_a?(kind) && node.name == name
+end

data/lib/kimera/registry/source_file.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "prism"
+require_relative "../memo_guard"
 require_relative "../memoization"
 require_relative "mutation_point"
 require_relative "walking"
@@ -25,6 +26,8 @@ class Kimera::RegistryScan::SourceFile
 
   def tainted = @_tainted ||= Kimera::Memoization.ranges(@source)
 
+  def guards = @_guards ||= Kimera::MemoGuard.exemptions(@source)
+
   def mined(root)
     found = []
     walk(root, origin) { |node, cursor| bank(found, node, cursor) }
@@ -36,7 +39,7 @@ class Kimera::RegistryScan::SourceFile
   end
 
   def bank(found, node, cursor)
-    pairs = harvest(applicable(cursor), node, cursor.position)
+    pairs = harvest(applicable(cursor), node, cursor.position).reject { |key, _| guarded?(node, key) }
     return if pairs.empty?
     found << assemble(node, pairs, cursor).taint!(tainted)
   end
@@ -46,6 +49,8 @@ class Kimera::RegistryScan::SourceFile
     cursor.position ? chosen : chosen.reject(&:statement?)
   end
 
+  def guarded?(node, key) = guards.include?(Kimera::MemoGuard::Exemption.new(node.location, key))
+
   def harvest(operators, node, position)
     operators.flat_map { |operator| operator.pairs(node, position: position) }
   end

data/lib/kimera/support/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kimera
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kimera
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Giacomo GK
@@ -99,6 +99,7 @@ files:
 - lib/kimera/cli/workflows.rb
 - lib/kimera/error.rb
 - lib/kimera/execution/baseline_failure.rb
+- lib/kimera/execution/baseline_failure/breakdown.rb
 - lib/kimera/execution/baseline_pass.rb
 - lib/kimera/execution/boot.rb
 - lib/kimera/execution/callback.rb
@@ -150,6 +151,7 @@ files:
 - lib/kimera/incremental/git_diff.rb
 - lib/kimera/incremental/selection.rb
 - lib/kimera/incremental/session.rb
+- lib/kimera/memo_guard.rb
 - lib/kimera/memoization.rb
 - lib/kimera/operators.rb
 - lib/kimera/operators/argument_drop.rb