kimera 0.1.5 → 0.1.6

data/lib/kimera/results/result.rb

@@ -15,7 +15,7 @@ module Kimera
   MutantResult =
     Struct.new(
       :mutant_id, :status, :file, :duration, :failing_tests, :covering_tests,
-      :detail,
+      :detail, :verdict,
       keyword_init: true
     ) do
       def duration
@@ -26,10 +26,22 @@ module Kimera
         Status::KILLING.include?(status)
       end
 
+      def lapsed?
+        Status::KILLING.include?(verdict)
+      end
+
       def isolated(detail)
         self.class.new(mutant_id: mutant_id, status: :isolated_only, file: file, duration: duration, detail: detail)
       end
 
+      def waive
+        self.class.new(**self.class.outcome(outcome), **waiver, mutant_id: mutant_id, file: file)
+      end
+
+      def waiver
+        { status: :ignored, verdict: status, detail: ["ignored (#{status})", detail].compact.join(": ") }
+      end
+
       def covered?
         !Status::UNJUDGED.include?(status)
       end
@@ -44,9 +56,11 @@ module Kimera
       end
 
       def identity
-        { "mutant_id" => mutant_id, "status" => status.to_s, "file" => file }
+        { "mutant_id" => mutant_id, "status" => status.to_s, "file" => file }.merge(judged)
       end
 
+      def judged = verdict ? { "verdict" => verdict.to_s } : {}
+
       def outcome
         { "duration" => duration, "failing_tests" => failing_tests }
           .merge("covering_tests" => covering_tests, "detail" => detail)
@@ -62,6 +76,7 @@ module Kimera
 
         def identity(hash)
           { mutant_id: hash["mutant_id"], status: hash["status"].to_sym, file: hash["file"] }
+            .merge(verdict: hash["verdict"]&.to_sym)
         end
 
         def outcome(hash)

data/lib/kimera/results/run_report.rb

@@ -95,8 +95,9 @@ class Kimera::RunReport
 
   def detailed(result)
     base = result.to_h
-    pair = @registry&.point(result.mutant_id)
-    pair ? base.merge(rewritten(pair)) : base
+    id = result.mutant_id
+    pair = @registry&.point(id)
+    pair ? base.merge("key" => @registry.keys[id]).merge(rewritten(pair)) : base
   end
 
   def rewritten(pair)

data/lib/kimera/scope/config.rb

@@ -40,7 +40,12 @@ module Kimera
       return {} unless File.exist?(file)
       options = normalize(YAML.safe_load_file(file) || {})
       baseline = options[:baseline]
-      baseline ? options.merge(ignore: Array(options[:ignore]) + ignores_from(baseline, file)) : options
+      baseline ? options.merge(baseline_ignore: ignores_from(baseline, file)) : options
+    end
+
+    def ignores(options)
+      local = Array(options[:ignore])
+      options[:baseline] ? local + Array(options[:baseline_ignore]) : local
     end
 
     def root(root: ".")

data/lib/kimera/scope/ignore_drift.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Kimera::IgnoreList::Drift
+  private
+
+  def hits = exact.empty? ? drifted : exact
+
+  def exact = @_exact ||= matching(anchors)
+
+  def drifted = @_drifted ||= anchors[:line] && anchors[:label] ? single(matching(anchors.except(:line))) : []
+
+  def single(found) = found.one? ? found : []
+end

data/lib/kimera/scope/ignore_list.rb

@@ -24,26 +24,31 @@ module Kimera
         end
       end
 
+    Resolution = Data.define(:ids, :stale, :moved)
+
+    Shift =
+      Data.define(:rule, :line) do
+        def to_s = "#{rule[:file]}:#{rule[:line]} → #{line} [#{rule[:label]}]"
+      end
+
     module_function
 
-    def ids(registry, rules)
-      rules = Array(rules)
-      registry.each.filter_map { |mutant, point| mutant.id if rules.any? { |rule| match?(rule, point, mutant) } }
+    def resolve(registry, rules)
+      candidates = Hash.new { |cache, glob| cache[glob] = pairs(registry, glob) }
+      placements = Array(rules).map { |rule| Placement.new(rule, candidates[rule[:file]]) }
+      Resolution.new(
+        ids: placements.flat_map(&:ids).uniq.sort,
+        stale: placements.select(&:stale?).map(&:rule), moved: placements.filter_map(&:moved)
+      )
     end
 
-    def stale(registry, rules)
-      Array(rules).select do |rule|
-        relevant?(rule, registry) && !any?(rule, registry)
-      end
-    end
+    def ids(registry, rules) = resolve(registry, rules).ids
 
-    def relevant?(rule, registry)
-      glob = rule[:file]
-      glob && registry.files.any? { |file| File.fnmatch?(glob, file, File::FNM_PATHNAME) }
-    end
+    def stale(registry, rules) = resolve(registry, rules).stale
 
-    def any?(rule, registry)
-      registry.each.any? { |mutant, point| match?(rule, point, mutant) }
+    def pairs(registry, glob)
+      files = glob ? registry.files.select { |file| File.fnmatch?(glob, file, File::FNM_PATHNAME) } : []
+      files.flat_map { |file| registry.at(file).flat_map { |point| point.mutants.map { |mutant| [mutant, point] } } }
     end
 
     ANCHORS = { line: :line?, column: :column?, label: :label? }.merge(method: :method?, original: :original?).freeze
@@ -53,3 +58,5 @@ module Kimera
     end
   end
 end
+
+require_relative "ignore_placement"

data/lib/kimera/scope/ignore_placement.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "ignore_drift"
+
+class Kimera::IgnoreList::Placement
+  include Kimera::IgnoreList::Drift
+
+  attr_reader :rule
+
+  def initialize(rule, pairs)
+    @rule = rule
+    @pairs = pairs
+  end
+
+  def ids = hits.map { |mutant, _point| mutant.id }
+
+  def stale? = hits.empty? && !@pairs.empty?
+
+  def moved
+    return unless exact.empty?
+    _mutant, point = drifted.first
+    Kimera::IgnoreList::Shift.new(@rule, point.location.start_line) if point
+  end
+
+  private
+
+  def anchors = @rule
+
+  def matching(rule) = @pairs.select { |mutant, point| Kimera::IgnoreList.match?(rule, point, mutant) }
+end

data/lib/kimera/self_protection.rb

@@ -20,6 +20,7 @@ module Kimera
       kimera/frameworks/rspec_adapter.rb
       kimera/frameworks/rspec_group_index.rb
       kimera/frameworks/minitest_adapter.rb
+      kimera/support/test_exit.rb
       kimera/execution/shift.rb
       kimera/execution/shift/attempt.rb
       kimera/execution/shift/deadline.rb

data/lib/kimera/support/test_exit.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Kimera
+end
+
+module Kimera::TestExit
+  module_function
+
+  def failure(error)
+    SystemExit.new(error.status, describe(error)).tap { |failure| failure.set_backtrace(error.backtrace) }
+  end
+
+  def describe(error)
+    text = "exit(#{error.status}) called from #{origin(error)}"
+    message = error.message
+    message == "exit" ? text : "#{text}: #{message}"
+  end
+
+  def origin(error) = error.backtrace.first.delete_prefix("#{Dir.pwd}#{File::SEPARATOR}")
+
+  module Example
+    private
+
+    def with_around_example_hooks
+      super
+    rescue SystemExit => error
+      set_exception(Kimera::TestExit.failure(error))
+    end
+  end
+
+  module Test
+    def capture_exceptions
+      super do
+        yield
+      rescue SystemExit => error
+        failures << ::Minitest::UnexpectedError.new(Kimera::TestExit.failure(error))
+      end
+    end
+  end
+end

data/lib/kimera/support/version.rb

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

data/skills/kimera/SKILL.md

@@ -44,7 +44,7 @@ bundle exec kimera doctor --check-baseline  # discovery, git, and a green suite
 bundle exec kimera changed                      # changed lines only (vs origin/main)
 bundle exec kimera run                          # full, per .kimera.yml
 bundle exec kimera report REPORT.json --status survived
-bundle exec kimera mutant ID --report REPORT.json
+bundle exec kimera mutant ID_OR_KEY --report REPORT.json [--rerun]
 bundle exec kimera run --isolated --jobs 4      # oracle mode (see Strengthen)
 ```
 
@@ -52,12 +52,19 @@ bundle exec kimera run --isolated --jobs 4      # oracle mode (see Strengthen)
   report, except isolated mode, which traces one verdict per line to stderr.
 - `--session FILE` persists per-mutant verdicts and resumes interrupted runs.
 - `--report FILE` writes the machine-readable report. Each result carries
-  `mutant_id`, `status`, `file`, `line`, `operator`, and the `original` ->
-  `mutated` source; don't re-parse the human log.
+  `mutant_id`, `key`, `status`, `file`, `line`, `operator`, and the
+  `original` -> `mutated` source; don't re-parse the human log.
+- Refer to a mutant by its `key` (`path:line:digest`), not its `mutant_id`.
+  The ID numbers every mutant in that run, so it changes with the set of
+  files scanned; the key doesn't. `kimera mutant` and `--focus` take either,
+  and a key still resolves after unrelated edits move its line.
 - Minitest/Rails: kimera puts `test/` (or `spec/`) on `$LOAD_PATH`, so test
   files can `require "test_helper"` without `RUBYOPT="-Itest"`.
 - `--tests` on the CLI *replaces* the config `tests:` glob (it does not
-  append).
+  append). A narrowed run's verdicts hold only for the narrowed set: a
+  survivor may be killed by a test left out, so confirm it with the full glob
+  before writing a test or an ignore entry. The report flags such a run
+  (`narrowed run: ...`, `"narrowed": true` in the JSON `run` section).
 - `--jobs` sizes the warm pool and isolated mirrors. Coverage-based test
   selection and kill-on-first-failure are automatic.
 - A `timeout` verdict is a *detected* mutant (the suite hung on it), not an
@@ -69,6 +76,9 @@ bundle exec kimera run --isolated --jobs 4      # oracle mode (see Strengthen)
   raise `--hard-timeout`. If it waits on something the workers share (a Redis
   db, a lock, a port), give each worker its own through a
   `parallelize_setup`/`after_fork_hook`.
+- Code under test that calls `exit` or `abort` fails that test (`detail`:
+  `SystemExit: exit(1) called from FILE:LINE`), so a mutant that makes a test
+  abort is `killed`, not `harness_error`.
 - A kill's `detail` holds the killing test's failure message and first
   frames. A state-leak warning names a test that failed in a warm worker for
   reasons unrelated to the mutant. Kimera already judged that mutant again on
@@ -87,6 +97,25 @@ bundle exec kimera run --isolated --jobs 4      # oracle mode (see Strengthen)
   an `--isolated` case. Its mutants report as `unmutatable` (never gating,
   never scored, with the reason in the detail), not `no_coverage`.
 
+## Burn down a baseline
+
+```sh
+bundle exec kimera run --evaluate-ignored --report r.json   # judge ignored mutants too
+bundle exec kimera baseline review .kimera-baseline.yml --report r.json
+bundle exec kimera baseline prune .kimera-baseline.yml --report r.json  # --dry-run first
+```
+
+- `--evaluate-ignored` keeps ignored mutants `ignored` (never a gating
+  survivor, still counted by `max_ignored`) but records each one's `verdict`.
+  Don't copy `.kimera.yml` to drop the `baseline:` line; `--no-baseline`
+  does that.
+- `review` sorts entries into killed (prune), still surviving (triage them
+  like any survivor), unjudged, stale, and out of scope. `prune` drops killed
+  and stale entries, moves re-anchored ones to their current line, and says
+  how far to lower `max_ignored`: lower it in the same diff.
+- A drifted line anchor re-anchors on its own when the label (and `original`)
+  single out one mutant; the `re-anchored` warning means update the entry.
+
 ## Triage a surviving mutant: the only four verdicts
 
 1. **Real gap**: write the test. Assert the exact distinction the mutant
@@ -102,6 +131,39 @@ bundle exec kimera run --isolated --jobs 4      # oracle mode (see Strengthen)
    or accept it visibly. Never stub internals just to kill a mutant; a test
    that pins the implementation makes the suite worse.
 
+### Survivors that recur on Rails apps
+
+These shapes survive again and again. Recognizing one tells you which verdict
+to test first. It never replaces the `--isolated` check.
+
+Usually **dead code**. The guard only saves a query, so delete it:
+
+- A guard before a query that already returns nil/false/0: `return false
+  unless user` before `memberships.exists?(user:)` on a NOT NULL column, or
+  `return if ids.empty?` before `where(id: ids)` / `update_all`.
+- A no-op write under dirty tracking: `update!(status: :past_due) unless
+  past_due?`. Rails skips the UPDATE when nothing changed. Delete the guard
+  unless callbacks or `updated_at` must not fire, and if they must, test
+  that.
+- A readiness check that compares constants with constants
+  (`REQUIRED - LIVE_STATES`). Nothing at runtime can change it, so assert it
+  once at load time or drop it.
+
+Usually **keep and ignore** (after `--isolated`, with the mechanism as the
+`reason:`), because the code hardens against something tests don't drive:
+
+- `reload` before `with_lock`/`lock!` on the same record, or double-checked
+  locking. `with_lock` reloads the row anyway, and only a real race tells
+  the two apart.
+- `transaction(requires_new: true)` around a `create!` that rescues
+  `RecordNotUnique`. It matters only when a concurrent insert wins.
+- Barrier or queue values that nothing reads (`ready << true`), and
+  timing-safe compares.
+
+Before you delete one of these guards, check that it doesn't also skip a side
+effect (a callback, a job, an audit row). If it does, the survivor is a real
+gap: test that side effect.
+
 ## Ignore discipline: hard rules (especially for agents)
 
 - **Raise `max_ignored` only for an entry that has earned it**: survival

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kimera
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Giacomo GK
@@ -72,6 +72,10 @@ files:
 - lib/kimera/cli.rb
 - lib/kimera/cli/argv.rb
 - lib/kimera/cli/baseline.rb
+- lib/kimera/cli/baseline/entry.rb
+- lib/kimera/cli/baseline/ledger.rb
+- lib/kimera/cli/baseline/prune.rb
+- lib/kimera/cli/baseline/review.rb
 - lib/kimera/cli/changed.rb
 - lib/kimera/cli/ci.rb
 - lib/kimera/cli/completion.rb
@@ -87,6 +91,7 @@ files:
 - lib/kimera/cli/run/digest.rb
 - lib/kimera/cli/run/emission.rb
 - lib/kimera/cli/run/gate.rb
+- lib/kimera/cli/run/narrowing.rb
 - lib/kimera/cli/run/options.rb
 - lib/kimera/cli/run/pass.rb
 - lib/kimera/cli/run/sources.rb
@@ -199,6 +204,7 @@ files:
 - lib/kimera/operators/vocabulary.rb
 - lib/kimera/plugins.rb
 - lib/kimera/registry/builder.rb
+- lib/kimera/registry/mutant_keys.rb
 - lib/kimera/registry/mutation_point.rb
 - lib/kimera/registry/numbering.rb
 - lib/kimera/registry/registry.rb
@@ -226,13 +232,16 @@ files:
 - lib/kimera/runtime.rb
 - lib/kimera/scope/config.rb
 - lib/kimera/scope/file_set.rb
+- lib/kimera/scope/ignore_drift.rb
 - lib/kimera/scope/ignore_list.rb
+- lib/kimera/scope/ignore_placement.rb
 - lib/kimera/self_protection.rb
 - lib/kimera/support/duration.rb
 - lib/kimera/support/errors.rb
 - lib/kimera/support/operator_protocol.rb
 - lib/kimera/support/syntax.rb
 - lib/kimera/support/syntax_types.rb
+- lib/kimera/support/test_exit.rb
 - lib/kimera/support/unparse.rb
 - lib/kimera/support/version.rb
 - lib/kimera/support/warnings.rb