kimera 0.1.0

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../../operators"
+require_relative "../../report/formats"
+require_relative "../../scope/config"
+require_relative "../../scope/file_set"
+require_relative "options"
+
+class Kimera::CLI::Run::Arguments
+  def parse(argv)
+    options = defaults.merge(Kimera::Config.parse(argv))
+    finish(options, Kimera::CLI::RunOptions::OPTIONS.parse(argv, options))
+  end
+
+  private
+
+  def finish(options, rest)
+    validate(options)
+    options.except(:cli_tests).merge(scoped(options, rest))
+  end
+
+  def validate(options) = Kimera::Report::Formats.new.normalize(options[:format])
+
+  def scoped(options, rest)
+    {
+      tests: Kimera::Config.prefer(options[:cli_tests], options[:tests], Kimera::CLI::RunOptions::DEFAULT_TESTS),
+      paths: Kimera::Config.prefer(rest, options[:paths], Kimera::FileSet::DEFAULT_GLOBS)
+    }.merge(arrays(options))
+  end
+
+  def arrays(options)
+    { exclude: Array(options[:exclude]), ignore: Array(options[:ignore]) }
+      .merge(isolate_when_covered_by: Array(options[:isolate_when_covered_by]), focus: Array(options[:focus]))
+  end
+
+  def defaults
+    core.merge(gates).merge(scope)
+  end
+
+  def core
+    { framework: "rspec", source_root: ".", tests: [] }
+      .merge(paths: nil, operators: Kimera::Operators::DEFAULT_KEYS, soft_timeout: 5.0)
+      .merge(hard_timeout: nil, leak_every: 10, registry: nil)
+      .merge(report: nil, format: "text", focus: [], gate: true, coverage: true, require: [])
+  end
+
+  def gates
+    { since: nil, session: nil, max_survivors: nil }.merge(max_ignored: nil, max_errors: 0, jobs: 1)
+  end
+
+  def scope
+    { exclude: [], exclude_tests: [], config: nil }
+      .merge(ignore: [], isolate_db: false, isolated: false)
+      .merge(fail_on_no_coverage: false, progress: nil, color: nil, quiet: false, verbose: false, log: nil)
+      .merge(isolate_when_covered_by: [])
+      .merge(cli_tests: [])
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../../incremental/selection"
+require_relative "../../incremental/session"
+require_relative "digest"
+require_relative "pass"
+require_relative "sources"
+
+class Kimera::CLI::Run::Cycle
+  def initialize(options, registry, changed, digest:)
+    @options = options
+    @registry = registry
+    @changed = changed
+    @digest = digest
+  end
+
+  def call
+    @digest.verbose(@options) if @options[:verbose]
+    scope(@changed && Kimera::Incremental::Selection.select(@registry, @changed))
+  end
+
+  private
+
+  def scope(selected)
+    eligible = focus(selected || @registry.each.map { |mutant, _| mutant.id })
+    ignored = Kimera::IgnoreList.ids(@registry, @options[:ignore]) & eligible
+    notify(selected, ignored)
+    session(eligible - ignored, ignored)
+  end
+
+  def notify(selected, ignored)
+    @digest.stale(@registry, @options[:ignore])
+    @digest.announce(selected, ignored, files: @registry.files.size, since: @options[:since])
+  end
+
+  def session(todo, ignored)
+    loaded = Kimera::Incremental::Session.load(@options[:session], registry: @registry)
+    perform(todo, loaded)
+    conclude(todo, ignored, loaded)
+  end
+
+  def perform(todo, loaded)
+    remaining = todo.reject { |id| loaded.done?(id) }
+    harness(remaining, loaded) unless remaining.empty?
+    path = @options[:session]
+    loaded.save(path, registry: @registry, meta: { "since" => @options[:since] }) if path
+  end
+
+  def conclude(todo, ignored, loaded)
+    report = loaded.report(todo, ignored, @registry)
+    @digest.emit(report, @registry, **emission)
+    @options[:gate] == false ? 0 : @digest.gate(report, @options)
+  end
+
+  def emission
+    { path: @options[:report], format: @options.fetch(:format, "text"), metadata: provenance }
+      .merge(coverage: coverage, log: @options[:log])
+  end
+
+  def coverage = @options[:fail_on_no_coverage] ? :list : :hint
+
+  def focus(eligible)
+    ids = Array(@options[:focus])
+    return eligible if ids.empty?
+    missing = ids - eligible
+    missing.empty? ? ids : raise(Kimera::UsageError, "focused mutant(s) not in scope: #{missing.join(", ")}")
+  end
+
+  def provenance
+    @options.slice(:framework, :source_root, :tests, :exclude_tests, :operators, :coverage, :isolated, :jobs)
+      .transform_keys(&:to_s)
+  end
+
+  def harness(remaining, loaded)
+    adapter = Kimera::Frameworks::Adapter.load(@options[:framework])
+    Kimera::CLI::Run::Pass.new(@registry, @options, adapter).call(remaining, loaded)
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../../results/run_report"
+require_relative "../../scope/ignore_list"
+require_relative "emission"
+require_relative "gate"
+
+class Kimera::CLI::Run::Digest
+  def initialize(emission:, io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+    @emission = emission
+  end
+
+  def emit(...) = @emission.emit(...)
+
+  def gate(report, options) = Kimera::CLI::Run::Gate.new(report, options).status(@errors)
+
+  def announce(selected, ignored, files:, since:)
+    incremental(selected, files, since) if selected
+    @io.puts("Ignoring #{ignored.size} mutant(s) marked equivalent.") unless ignored.empty?
+  end
+
+  def stale(registry, rules)
+    Kimera::IgnoreList.stale(registry, rules).each { |rule| @errors.puts(anchor(rule)) }
+  end
+
+  def verbose(options)
+    @io.puts(
+      "Kimera: framework=#{options[:framework]} jobs=#{options[:jobs]} " \
+        "sources=#{Array(options[:paths]).join(",")} tests=#{Array(options[:tests]).join(",")} " \
+        "format=#{options.fetch(:format, "text")}"
+    )
+  end
+
+  private
+
+  def incremental(selected, files, since)
+    @io.puts("Incremental: #{selected.size} mutants on lines changed since #{since} (#{files} changed files).")
+  end
+
+  def anchor(rule)
+    "kimera: warning: ignore entry matches no mutant (stale anchor?): #{spot(rule)} #{rule[:label]}".rstrip
+  end
+
+  def spot(rule)
+    [rule[:file], rule[:line]].compact.join(":")
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "stringio"
+require_relative "../../report/coloring"
+require_relative "../../report/formats"
+require_relative "../../report/text"
+
+class Kimera::CLI::Run::Emission
+  include Kimera::Report::Coloring
+
+  def initialize(io: $stdout, output: io, color: nil, quiet: false)
+    @io = io
+    @output = output
+    @color = color
+    @quiet = quiet
+  end
+
+  def emit(report, registry, path: nil, format: "text", metadata: nil, coverage: :hint, log: nil)
+    text = rendered(report, registry, coverage, path)
+    document = report.document(metadata)
+    present(text, format, document)
+    save(log, text) if log
+    save(path, JSON.pretty_generate(document)) if path
+  end
+
+  private
+
+  def rendered(report, registry, coverage, path)
+    io = StringIO.new
+    Kimera::Report::Text.new(registry, io: io, color: color?).report(report, coverage: coverage, path: path)
+    io.string
+  end
+
+  def present(text, format, document)
+    return Kimera::Report::Formats.new(io: @output).render(format, document) unless format == "text"
+    @io.write(text) unless @quiet
+  end
+
+  def save(file, text)
+    FileUtils.mkdir_p(File.dirname(file))
+    File.write(file, text)
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class Kimera::CLI::Run::Gate
+  def initialize(report, options)
+    @report = report
+    @options = options
+  end
+
+  def status(stream)
+    return 0 if reasons.empty?
+    reasons.each { |reason| stream.puts("kimera: gate failed: #{reason}") }
+    2
+  end
+
+  private
+
+  def reasons = @_reasons ||= [survivors, coverage, ignored, unjudged].compact
+
+  def survivors
+    max = @options[:max_survivors]
+    count = @report.survived.size
+    return unless max ? count > max : count.positive?
+    "survivors=#{count} > max_survivors=#{max || 0}"
+  end
+
+  def coverage
+    uncovered = @report.uncovered.size
+    return unless @options[:fail_on_no_coverage] && uncovered.positive?
+    "#{uncovered} mutant(s) with no covering test (--fail-on-no-coverage)"
+  end
+
+  def ignored
+    cap = @options[:max_ignored]
+    count = @report.statuses(:ignored).size
+    "ignored=#{count} > max_ignored=#{cap}" if cap && count > cap
+  end
+
+  def unjudged
+    count = @report.errors.size
+    cap = Integer(@options[:max_errors] || 0)
+    "unjudged=#{count} > max_errors=#{cap}" if count > cap
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../flag"
+
+module Kimera
+end
+
+class Kimera::CLI
+end
+
+module Kimera::CLI::RunOptions
+  DEFAULT_TESTS = ["spec/**/*_spec.rb"].freeze
+
+  OPTIONS = Kimera::FlagTable.new(
+    banner: "Usage: kimera run [paths...] [options]\n" \
+      "Exit codes: 0 gates passed, 1 usage or setup error, 2 gate failed",
+    flags: [
+      Kimera::Flag.build("--framework NAME", :framework, "Test framework (rspec)"),
+      Kimera::Flag.build(
+        "--tests GLOB", :cli_tests,
+        "Test file glob (repeatable; replaces config tests:)", collect: true
+      ),
+      Kimera::Flag.build("--source-root DIR", :source_root, "Project root for synthesis"),
+      Kimera::REGISTRY_FLAG,
+      Kimera::OPERATORS_FLAG,
+      Kimera::REQUIRE_FLAG,
+      Kimera::Flag.build("--soft-timeout SEC", :soft_timeout, "Per-test soft timeout", type: Float),
+      Kimera::Flag.build("--hard-timeout SEC", :hard_timeout, "Per-mutant hard watchdog timeout", type: Float),
+      Kimera::Flag.build("--leak-every N", :leak_every, "Re-check a killed mutant every N", type: Integer),
+      Kimera::Flag.build("--[no-]coverage", :coverage, "Run each mutant only against covering tests (default: on)"),
+      Kimera::Flag.build("--since REF", :since, "Incremental: only mutate lines changed vs REF (git diff)"),
+      Kimera::Flag.build("--session FILE", :session, "Persist/resume per-mutant results in FILE"),
+      Kimera::Flag.build(
+        "--focus ID", :focus, "Evaluate only one or more mutant IDs (repeatable)",
+        type: Integer, collect: true
+      ),
+      Kimera::Flag.build("--[no-]gate", :gate, "Return gate status (default: on; use --no-gate for exploration)"),
+      Kimera::Flag.build("--max-survivors N", :max_survivors, "Gate: fail only if survivors exceed N", type: Integer),
+      Kimera::Flag.build(
+        "--max-ignored N", :max_ignored,
+        "Gate: fail if more than N mutants are ignore-listed", type: Integer
+      ),
+      Kimera::Flag.build(
+        "--max-errors N", :max_errors,
+        "Gate: fail if more than N mutants could not be judged (default 0)", type: Integer
+      ),
+      Kimera::Flag.build(
+        "--[no-]fail-on-no-coverage", :fail_on_no_coverage,
+        "Gate: also fail when any mutant in scope has no covering test"
+      ),
+      Kimera::Flag.build("--jobs N", :jobs, "Concurrent workers (warm pool / isolated mirrors)", type: Integer),
+      Kimera::Flag.build(
+        "--[no-]progress", :progress, "Live progress bar on stderr (default: on when stderr is a tty)"
+      ),
+      Kimera::Flag.build(
+        "--[no-]color", :color,
+        "Color text output (default: on when stdout is a tty; respects NO_COLOR)"
+      ),
+      Kimera::Flag.build(["-q", "--quiet"], :quiet, "Suppress the final human-readable report"),
+      Kimera::Flag.build(["-v", "--verbose"], :verbose, "Print resolved scope and execution settings"),
+      Kimera::Flag.build("--log FILE", :log, "Write the final human-readable report to FILE"),
+      Kimera::Flag.build(
+        "--[no-]isolate-db", :isolate_db, "Wrap each mutant in a rolled-back ActiveRecord transaction"
+      ),
+      Kimera::Flag.build(
+        "--isolated", :isolated,
+        "Evaluate every mutant in a fresh subprocess (slow, but trustworthy for " \
+          "the runtime selector and harness-critical code)"
+      ),
+      Kimera::Flag.build(
+        "--isolate-when-covered-by SUBSTR", :isolate_when_covered_by,
+        "Isolate only mutants whose covering set includes a test id matching SUBSTR " \
+          "(repeatable) — a fast, targeted alternative to --isolated for pool-unsafe specs",
+        collect: true
+      ),
+      Kimera::Flag.build("--exclude GLOB", :exclude, "Exclude matching files (repeatable)", collect: true),
+      Kimera::Flag.build(
+        "--exclude-test GLOB", :exclude_tests, "Exclude matching test files (repeatable)", collect: true
+      ),
+      Kimera::CONFIG_FLAG,
+      Kimera::Flag.build("--report FILE", :report, "Write the canonical JSON report to FILE"),
+      Kimera::Flag.build("--format NAME", :format, "Output: text, json, ndjson, github, or sarif (default: text)")
+    ]
+  )
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../../execution/harness"
+require_relative "../../execution/isolated"
+require_relative "../../frameworks/adapter"
+require_relative "../../report/progress"
+require_relative "../../results/run_report"
+require_relative "../../self_protection"
+require_relative "sources"
+
+class Kimera::CLI::Run::Pass
+  def initialize(registry, options, adapter)
+    @registry = registry
+    @options = options
+    @adapter = adapter
+  end
+
+  def call(remaining, session)
+    report = with_adapter { perform(remaining) }
+    session.merge!(report)
+    report
+  end
+
+  private
+
+  def progress = @_progress ||= Kimera::Report::Progress.new(enabled: @options[:progress])
+
+  def with_adapter
+    yield
+  ensure
+    @adapter&.finish
+  end
+
+  def perform(remaining)
+    warm
+    run(remaining)
+  end
+
+  def harness = @_harness ||= Kimera::Execution::Harness.new(**settings)
+
+  def files
+    @_files ||= Kimera::CLI::Run::Sources.new.expand(
+      @options[:tests], @options[:exclude_tests], "test", "check --tests"
+    )
+  end
+
+  def settings
+    base.merge({ hard_timeout: @options[:hard_timeout] }.compact)
+  end
+
+  def base
+    { registry: @registry, adapter: @adapter, source_root: @options[:source_root] }
+      .merge(soft_timeout: @options[:soft_timeout], leak_every: @options[:leak_every], jobs: @options[:jobs])
+      .merge(isolate_db: @options[:isolate_db], progress: progress)
+  end
+
+  def warm
+    if @options[:isolated] || @options[:coverage]
+      harness.warm!(files)
+    else
+      harness.without_coverage!(files)
+    end
+  end
+
+  def run(remaining)
+    isolated = ->(ids) { isolation.run(ids: ids, label: "mutants (isolated)") }
+    return isolated.call(remaining) if @options[:isolated]
+    pooled(remaining, isolated)
+  end
+
+  def pooled(remaining, isolated)
+    apart, together = split(remaining)
+    return harness.run(ids: together, label: "mutants") if apart.empty?
+    harness.run(ids: together, label: "mutants (warm)").merge(isolated.call(apart))
+  end
+
+  def isolation
+    Kimera::Execution::IsolatedExecution.new(**core, **{ hard_timeout: @options[:hard_timeout] }.compact)
+  end
+
+  def core
+    { registry: @registry, root: @options[:source_root], tests: @adapter.test_ids }
+      .merge(coverage: harness.coverage, progress: progress, jobs: @options[:jobs])
+      .merge(framework: @options[:framework], test_files: files)
+  end
+
+  def split(ids)
+    patterns = Array(@options[:isolate_when_covered_by])
+    ids.partition do |id|
+      critical?(id) || patterns.any? { |pattern| matches?(harness.coverage, id, pattern) }
+    end
+  end
+
+  def critical?(id) = Kimera::SelfProtection.critical?(@registry.index.fetch(id).file)
+
+  def matches?(coverage, id, pattern)
+    tests = coverage.fetch(id) { coverage.fetch(id.to_s, []) }
+    tests.any? { |test| test.include?(pattern) }
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../../error"
+require_relative "../../incremental/git_diff"
+require_relative "../../operators"
+require_relative "../../registry/builder"
+require_relative "../../registry/registry"
+require_relative "../../scope/file_set"
+
+class Kimera::CLI::Run::Sources
+  class << self
+    def changed(options)
+      Kimera::Incremental::GitDiff.lines(since: options[:since], root: options[:source_root])
+    end
+  end
+
+  def initialize(errors: $stderr)
+    @errors = errors
+  end
+
+  def load(options, changed = nil)
+    stored = options[:registry]
+    return Kimera::Registry.load(stored) if stored
+    build(options, files(options, changed))
+  end
+
+  def files(options, changed)
+    found = expand(options[:paths], options[:exclude], "source", "check paths and --exclude")
+    return found unless changed
+    root = File.expand_path(options[:source_root])
+    found.select { |file| changed.key?(Kimera::FileSet.relative(file, root)) }
+  end
+
+  def expand(patterns, exclude, kind, hint)
+    notice(patterns, exclude, kind)
+    found = Kimera::FileSet.expand(patterns, exclude: exclude)
+    raise(Kimera::UsageError, "no #{kind} files matched: #{Array(patterns).join(", ")} (#{hint})") if found.empty?
+    found
+  end
+
+  def notice(patterns, exclude, kind)
+    Kimera::FileSet.unused(patterns, exclude).each do |pattern|
+      @errors.puts("kimera: warning: exclude pattern matched no #{kind} files: #{pattern}")
+    end
+  end
+
+  private
+
+  def build(options, files)
+    Kimera::RegistryScan.new(
+      operators: Kimera::Operators.build(keys: options[:operators]),
+      root: options[:source_root],
+      shielded: !options[:isolated]
+    ).build(files)
+  end
+end

data/lib/kimera/cli/run.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../plugins"
+
+module Kimera
+end
+
+class Kimera::CLI
+end
+
+class Kimera::CLI::Run
+end
+
+require_relative "run/arguments"
+require_relative "run/cycle"
+require_relative "run/digest"
+require_relative "run/options"
+require_relative "run/sources"
+
+class Kimera::CLI::Run
+  include Kimera::CLI::RunOptions
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    cycle(parse(argv)).call
+  rescue Kimera::Error => error
+    @errors.puts("kimera: #{error.message}")
+    1
+  end
+
+  private
+
+  def parse(argv) = Kimera::CLI::Run::Arguments.new.parse(argv)
+
+  def cycle(options)
+    Kimera::Plugins.load!(options[:require], root: options[:source_root])
+    changed = options[:since] ? Kimera::CLI::Run::Sources.changed(options) : nil
+    registry = Kimera::CLI::Run::Sources.new(errors: @errors).load(options, changed)
+    Kimera::CLI::Run::Cycle.new(options, registry, changed, digest: digest(options))
+  end
+
+  def digest(options = {})
+    narration = options.fetch(:format, "text") == "text" ? @io : @errors
+    emission = Kimera::CLI::Run::Emission.new(io: narration, output: @io, **options.slice(:color, :quiet))
+    Kimera::CLI::Run::Digest.new(io: narration, errors: @errors, emission: emission)
+  end
+end

data/lib/kimera/cli/skill.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Kimera::CLI::Skill
+  PATH = File.expand_path("../../../skills/kimera/SKILL.md", __dir__)
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    return usage unless argv.empty?
+    @io.write(File.read(PATH))
+    0
+  end
+
+  private
+
+  def usage
+    @errors.puts("kimera: usage: kimera skill")
+    1
+  end
+end

data/lib/kimera/cli/suggestion.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kimera
+end
+
+class Kimera::CLI
+end
+
+class Kimera::CLI::Suggestion
+  MAX_EDITS = 3
+
+  def initialize(known)
+    @known = known
+  end
+
+  def hint(word)
+    nearest = @known.min_by { |candidate| distance(word, candidate) }
+    nearest && distance(word, nearest) <= MAX_EDITS ? "; did you mean #{nearest.inspect}?" : ""
+  end
+
+  private
+
+  def distance(left, right)
+    left.each_char.with_index(1).reduce(origin(right)) do |above, (char, index)|
+      below(above, right.each_char.map { |other| other == char ? 0 : 1 }, index)
+    end.last
+  end
+
+  def origin(word) = (0..word.length).to_a
+
+  def below(above, costs, index)
+    costs.each_with_index.reduce([index]) do |row, (cost, column)|
+      row << [above[column + 1] + 1, row[column] + 1, above[column] + cost].min
+    end
+  end
+end