kimera 0.1.0

data/lib/kimera/synthesis/guardrail_interpolation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Kimera
+  module GuardrailInterpolation
+    INTERPOLATING = %i[dstr dsym regexp xstr].freeze
+
+    private
+
+    def type?(node, type)
+      node.is_a?(Parser::AST::Node) && node.type == type
+    end
+
+    def string?(node)
+      type?(node, :str)
+    end
+
+    def empty?(node)
+      string?(node) && node.children.first == ""
+    end
+
+    def interpolation?(node)
+      type?(node, :begin)
+    end
+
+    def flatten(node)
+      spliced = node.children.flat_map { |child| type?(child, :dstr) ? child.children : [child] }
+      spliced = merge(spliced) if spliced.any? { |child| interpolation?(child) }
+      node.updated(nil, spliced)
+    end
+
+    def merge(children)
+      children.each_with_object([]) { |child, items| append(items, child) }
+    end
+
+    def append(items, child)
+      previous = items.last
+      return items << child unless string?(child) && string?(previous)
+      items[-1] = ast(:str, previous.children.first + child.children.first)
+    end
+
+    def prune(node)
+      Kimera::Rewrite::AstWalk.rebuild(node) do |rebuilt, _original|
+        INTERPOLATING.include?(rebuilt.type) ? filter(rebuilt) : rebuilt
+      end
+    end
+
+    def filter(node)
+      kept = node.children.reject { |child| empty?(child) }
+      return ast(:str, "") if node.type == :dstr && kept.empty?
+      collapse(node, kept)
+    end
+
+    def collapse(node, kept)
+      first = kept.first
+      return first if node.type == :dstr && kept.one? && %i[str dstr].include?(first.type)
+      node.updated(nil, kept)
+    end
+  end
+end

data/lib/kimera/synthesis/guardrail_value_objects.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kimera
+  module GuardrailValueObjects
+    VALUE_OBJECT_FACTORIES = { Struct: :new, Data: :define }.freeze
+
+    private
+
+    def reopen(node)
+      return node unless node.type == :casgn
+      scope, name, value = node.children
+      return node unless type?(value, :block)
+      block(node, scope, name, value)
+    end
+
+    def block(node, scope, name, value)
+      factory, _arguments, body = value.children
+      return node unless factory?(factory)
+      reopened(node, scope, name, factory, body)
+    end
+
+    def reopened(node, scope, name, factory, body)
+      ast(
+        :begin,
+        node.updated(nil, [scope, name, constant(ast(:begin, scope || context), ast(:sym, name), factory)]),
+        ast(:block, ast(:send, ast(:const, scope, name), :class_eval), ast(:args), body)
+      )
+    end
+
+    def constant(base, sym, factory)
+      ast(:if, ast(:send, base, :const_defined?, sym, ast(:false)), ast(:send, base, :const_get, sym), factory)
+    end
+
+    def context
+      identity = ast(:self)
+      root = ast(:cbase)
+      ast(:if, ast(:send, identity, :is_a?, ast(:const, root, :Module)), identity, ast(:const, root, :Object))
+    end
+
+    def factory?(call)
+      return false unless type?(call, :send)
+      receiver, selector = call.children
+      type?(receiver, :const) && VALUE_OBJECT_FACTORIES[receiver.children[1]] == selector
+    end
+  end
+end

data/lib/kimera/synthesis/overlay.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../operators/base"
+
+require_relative "../support/unparse"
+
+require_relative "../error"
+require_relative "../registry/registry"
+require_relative "guard_weaver"
+require_relative "source_map"
+
+class Kimera::Overlay
+  Result =
+    Struct.new(:file, :source, :mutant_ids, :skipped_unsafe, keyword_init: true) do
+      def install(path)
+        Kimera::Overlay.evaluate(source, path)
+        mutant_ids
+      end
+    end
+
+  def initialize(registry)
+    @registry = registry
+  end
+
+  class << self
+    def evaluate(source, path)
+      Kimera::Warnings.silence { TOPLEVEL_BINDING.eval(source, path) }
+    end
+  end
+
+  def synthesize(file, source)
+    safe, unsafe = @registry.at(file).partition(&:safe?)
+    return unsafe(file, source, unsafe) if safe.empty?
+    Kimera::Overlay::FileWeave.new(file, Kimera::SourceMap.new(source), safe, unsafe).result
+  end
+
+  def bake(_file, source, id)
+    pair = @registry.point(id)
+    return source unless pair
+    mutant, point = pair
+    map = Kimera::SourceMap.new(source)
+    map.restore(Kimera::Unparse.unparse(Kimera::Guardrail.new(map, []).bake(point.location, mutant.directive)))
+  end
+
+  private
+
+  def unsafe(file, source, points)
+    Result.new(file: file, source: source, mutant_ids: [], skipped_unsafe: points.flat_map(&:ids))
+  end
+end
+
+require_relative "file_weave"

data/lib/kimera/synthesis/overlay_splice.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Kimera
+  module OverlaySplice
+    private
+
+    def splice
+      prepared = prepare
+      prepared && report(*prepared)
+    end
+
+    def prepare
+      return unless ready?
+      edits, dropped = gather
+      return if edits.empty?
+      source = apply(edits)
+      [edits, dropped, source] if Kimera::Syntax.parse(source).success?
+    end
+
+    def gather
+      edits = []
+      dropped = []
+      each { |definition, points| collect(definition, points, edits, dropped) }
+      [edits, dropped]
+    end
+
+    def collect(definition, points, edits, dropped)
+      rewritten = rewrite(definition, points)
+      rewritten ? edits << rewritten : dropped.concat(points)
+    end
+
+    def report(edits, dropped, source)
+      applied = edits.flat_map(&:last)
+      announce(applied, dropped)
+      build(applied, dropped, source)
+    end
+
+    def build(applied, dropped, source)
+      Kimera::Overlay::Result.new(
+        file: @file, source: source, mutant_ids: applied,
+        skipped_unsafe: (@unsafe + dropped).flat_map(&:ids)
+      )
+    end
+
+    def announce(applied, dropped)
+      io.puts(
+        "kimera: #{@file}: file-level round-trip failed; " \
+          "#{applied.size} mutant(s) spliced per method, " \
+          "#{dropped.flat_map(&:ids).size} reported no_coverage"
+      )
+    end
+
+    def ready?
+      Kimera::Guardrail.new(@map, []).tree
+      true
+    rescue StandardError
+      false
+    end
+
+    def each(&)
+      claimed = []
+      definitions.each { |definition| visit(definition, claimed, &) }
+    end
+
+    def visit(definition, claimed)
+      mine = points(definition, claimed)
+      return if mine.empty?
+      claimed.concat(mine)
+      yield(definition, mine)
+    end
+
+    def points(definition, claimed)
+      from, to = @map.span(definition.location.expression)
+      @safe.select { |point| !claimed.include?(point) && point.location.within?(from, to) }
+    end
+
+    def definitions
+      nodes = []
+      Kimera::Rewrite::AstWalk.visit(@map.ast) { |node| nodes << node if %i[def defs].include?(node.type) }
+      nodes
+    end
+
+    def rewrite(definition, points)
+      text, applied = Kimera::Guardrail.new(@map, points).rewrite(definition)
+      span(definition) + [text, applied]
+    rescue StandardError
+      nil
+    end
+
+    def span(definition)
+      expression = definition.location.expression
+      [expression.begin_pos, expression.end_pos]
+    end
+
+    def apply(edits)
+      edits.sort_by(&:first).reverse_each.with_object(@map.source.dup) do |(from, to, replacement, _ids), text|
+        text[from...to] = replacement
+      end
+    end
+  end
+end

data/lib/kimera/synthesis/project.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "overlay"
+
+module Kimera
+  module Synthesis
+  end
+end
+
+class Kimera::Synthesis::Project
+  Manifest =
+    Struct.new(:files, :mutant_files, :unsafe_mutants, keyword_init: true) do
+      def record(file, dest, result)
+        files[file] = dest
+        result.mutant_ids.each { |id| mutant_files[id] = file }
+        unsafe_mutants.concat(result.skipped_unsafe)
+      end
+    end
+
+  def initialize(registry, root: ".")
+    @registry = registry
+    @root = root
+  end
+
+  def write(outdir)
+    outdir = File.expand_path(outdir)
+    @registry.files.each { |file| copy(file, outdir) }
+    manifest
+  end
+
+  private
+
+  def manifest
+    @_manifest ||= Manifest.new(files: {}, mutant_files: {}, unsafe_mutants: [])
+  end
+
+  def copy(file, outdir)
+    source = File.join(root, file)
+    return unless File.file?(source)
+    emit(file, outdir, synth.synthesize(file, File.read(source, encoding: Encoding::UTF_8)))
+  end
+
+  def root
+    @_root ||= File.expand_path(@root)
+  end
+
+  def synth
+    @_synth ||= Kimera::Overlay.new(@registry)
+  end
+
+  def emit(file, outdir, result)
+    dest = File.join(outdir, file)
+    FileUtils.mkdir_p(File.dirname(dest))
+    File.write(dest, result.source)
+    manifest.record(file, dest, result)
+  end
+end

data/lib/kimera/synthesis/source_map.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../support/unparse"
+require_relative "../rewrite/numbered_params"
+
+class Kimera::SourceMap
+  attr_reader :source
+
+  def initialize(source)
+    @source = source
+  end
+
+  def ast
+    @_ast ||= Kimera::Rewrite::NumberedParams.normalize(Kimera::Unparse.parse(@source))
+  end
+
+  def span(expr)
+    [bytes[expr.begin_pos], bytes[expr.end_pos]]
+  end
+
+  def restore(source)
+    prefix = comments.join("\n")
+    prefix.empty? ? source : "#{prefix}\n#{source}"
+  end
+
+  MAGIC_COMMENT =
+    /\A#\s*(?:-\*-.*-\*-|(?:frozen_string_literal|encoding|coding|warn_indent|shareable_constant_value)\s*:)/i
+  private_constant :MAGIC_COMMENT
+
+  private
+
+  def comments
+    first, second = @source.lines
+    shebang = first&.start_with?("#!") ? first : nil
+    candidate = shebang ? second : first
+    [shebang, (candidate&.match?(MAGIC_COMMENT) ? candidate : nil)].compact.map(&:chomp)
+  end
+
+  def bytes
+    @_bytes ||= @source.each_char.map(&:bytesize).each_with_object([0]) { |size, map| map << (map.last + size) }
+  end
+end

data/lib/kimera/version.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "support/version"

data/lib/kimera.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "kimera/error"
+require_relative "kimera/runtime"
+require_relative "kimera/version"
+
+module Kimera
+  autoload :MutationPoint, "kimera/registry/mutation_point"
+  autoload :Registry, "kimera/registry/registry"
+  autoload :RegistryScan, "kimera/registry/builder"
+  autoload :Overlay, "kimera/synthesis/overlay"
+  autoload :CLI, "kimera/cli"
+end

data/skills/kimera/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: kimera
+description: >-
+  Running, triaging, and gating mutation tests with kimera in a Ruby or Rails
+  project. Use when running kimera, triaging surviving mutants, deciding
+  whether to add a test, adding or reviewing ignore or baseline entries,
+  raising max_ignored, wiring kimera into CI, or reading a kimera report.
+---
+
+# Strengthening a suite with kimera
+
+Mutation testing audits *tests*, not code. The unit of work is one surviving
+mutant, and each gets exactly one of four verdicts (see Triage). Never act to
+move the score.
+
+## Set up
+
+```sh
+bundle exec kimera init                     # detects the project, writes .kimera.yml
+bundle exec kimera doctor --check-baseline  # discovery, git, and a green suite
+```
+
+- Gates: keep `max_survivors: 0`; every survivor is a decision, not a
+  statistic. `max_ignored` rises only in the same diff as the entry it admits.
+- Adopting on a suite with existing survivors: `kimera baseline create
+  REPORT.json --reason TEXT` records them as reviewed debt, so the gate blocks
+  only new holes. Burn the baseline down; never grow it to pass a gate.
+- Fix line coverage first. `no_coverage` mutants are plain coverage gaps, and
+  mutation results only mean something for code the tests execute.
+- CI shape: **PR gate is incremental** (`kimera ci --since origin/main
+  --session tmp/kimera.json`; `ci` defaults to `--max-survivors 0
+  --fail-on-no-coverage`): no new surviving mutants on changed lines.
+  **Full run nightly**, not per-PR.
+- Exit codes: 0 pass; 1 invalid invocation or unmutated suite not green (fix
+  the suite, not kimera); 2 gate failure (survivors, uncovered, ignore budget,
+  or unjudged).
+- The green check covers only tests that *cover* an in-scope mutant. A red
+  test touching none of them is reported and excluded, so an unrelated flaky
+  spec doesn't abort a per-module run.
+
+## Operate
+
+```sh
+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 run --isolated --jobs 4      # oracle mode (see Strengthen)
+```
+
+- The progress bar renders on a tty. Redirected/CI runs stay silent until the
+  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.
+- 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).
+- `--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
+  error.
+- On a Rails app that uses `parallelize`, `--jobs > 1` gives each worker its
+  own database, so there's no shared-DB fixture/RLS deadlock.
+- Operators: the default is the conservative core. `--operators all` enables
+  the extended families; `--operators rails` (or `comparison,rails`) the
+  Rails-aware ones.
+- `isolated_only` marks class-body DSL mutants that only `--isolated` can
+  judge. Run it for their verdicts; they never gate or count in the score.
+- Rails `enum` models overlay warm (the re-declaration is idempotent), so
+  their method-body mutants are judged like any other. A file labeled
+  `unmutatable` could not be overlaid (a distinct, reported reason); it is not
+  an `--isolated` case.
+
+## Triage a surviving mutant: the only four verdicts
+
+1. **Real gap**: write the test. Assert the exact distinction the mutant
+   erased (the `<` vs `<=` boundary, the deleted call's observable effect).
+2. **Equivalent**: ignore entry, only with *both* (a) survival in an
+   `--isolated` oracle run and (b) a `reason:` naming the **mechanism**
+   ("IO.pipe write ends are sync; the flush is redundant"), not restating the
+   verdict ("this is equivalent"). Entries without `reason:` are rejected.
+3. **Dead code**: delete the code. A survivor on a branch nothing observes
+   is YAGNI evidence.
+4. **Wrong level**: the behavior is real but invisible to unit assertions
+   (logging, fd hygiene, progress output). Cover it with an integration test
+   or accept it visibly. Never stub internals just to kill a mutant; a test
+   that pins the implementation makes the suite worse.
+
+## Ignore discipline: hard rules (especially for agents)
+
+- **Never raise `max_ignored` to make a gate pass.** Raising the budget is a
+  human decision. Surface the failing gate and the candidate entry instead.
+- An ignore entry without an isolated-oracle survival check is inadmissible.
+  Warm-path survivors can be measurement artifacts (kimera's own suite once
+  had a "clearly equivalent" mutant that 11 specs actually kill).
+- A budget raise goes in the same diff as the entry it admits. Reviewers
+  judge the `reason:`, not the number.
+
+## Strengthen
+
+- Prioritize by blast radius: boundaries, money, authz, parsers, state
+  machines first; CLI wiring and glue last.
+- **Verify a kill by hand when in doubt**: apply the mutation to the source
+  manually, run the covering tests, confirm red, restore. This catches both
+  false survivors and false kills.
+- Suspicious verdicts on self-referential or harness-critical code (the test
+  runner, global state the suite also touches, kimera's own plumbing):
+  adjudicate with `--isolated`. Suites that manipulate shared globals can
+  suppress the warm path.
+- A cluster of `error`/`timeout` verdicts in one region usually means harness
+  fragility or a missing guard, not test strength. Read the cluster before
+  counting the detections.
+- Anti-patterns: chasing the score; adding tests without reading the mutant;
+  white-box tests that mirror the implementation; reclassifying killable
+  mutants as equivalent to end a triage session.