kimera 0.1.0

data/lib/kimera/audit/operator_audit.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../support/unparse"
+require_relative "../registry/builder"
+require_relative "../rewrite/directive"
+
+class Kimera::Operators::Audit
+  OK = :ok
+  UNRENDERABLE = :unrenderable
+  IDENTICAL = :identical
+
+  Finding =
+    Data.define(:operator, :original, :label, :rendered, :verdict) do
+      def ok? = verdict == OK
+
+      def to_s = "#{operator}: #{label}\n  #{original}\n  -> #{rendered.inspect} (#{verdict})"
+    end
+
+  Rendering =
+    Data.define(:original, :rendered) do
+      def verdict
+        return UNRENDERABLE unless rendered
+        rendered == reprinted ? IDENTICAL : OK
+      end
+      private
+      def reprinted
+        Kimera::Unparse.unparse(Kimera::Unparse.parse(original))
+      rescue StandardError
+        original
+      end
+    end
+
+  class << self
+    def audit(operators, source, file: "audit.rb")
+      new(operators).audit(source, file: file)
+    end
+
+    def faults(operators, source, file: "audit.rb")
+      audit(operators, source, file: file).reject(&:ok?)
+    end
+  end
+
+  def initialize(operators)
+    @operators = operators
+  end
+
+  def audit(source, file: "audit.rb")
+    scan(source, file).points.flat_map { |point| findings(point) }
+  end
+
+  private
+
+  def operators = Array(@operators)
+
+  def scan(source, file)
+    Kimera::RegistryScan.new(operators: operators).source(source, file: file)
+  end
+
+  def findings(point)
+    key, original, mutants = point.project(:operator, :original_source, :mutants)
+    mutants.map { |mutant| finding(key, original, mutant) }
+  end
+
+  def finding(key, original, mutant)
+    rendered = Kimera::Rewrite::Directive.render(original, mutant.directive)
+    Finding.new(
+      operator: key, original: original, label: mutant.label,
+      rendered: rendered, verdict: Rendering.new(original, rendered).verdict
+    )
+  end
+end

data/lib/kimera/cli/argv.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kimera
+end
+
+class Kimera::CLI
+end
+
+module Kimera::CLI::Argv
+  module_function
+
+  def option?(args, name) = args.any? { |arg| arg == name || arg.start_with?("#{name}=") }
+
+  def any?(args, names) = names.any? { |name| option?(args, name) }
+end

data/lib/kimera/cli/baseline.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../error"
+require_relative "flag"
+require_relative "report_file"
+
+class Kimera::CLI::Baseline
+  COMMANDS = { "create" => :create, "review" => :review }.freeze
+  ENTRY_KEYS = %w[file line label].freeze
+
+  CREATE = Kimera::FlagTable.new(
+    banner: "Usage: kimera baseline create REPORT.json --reason TEXT [--output FILE]",
+    flags: [
+      Kimera::Flag.build("--reason TEXT", :reason, "Why this existing mutation debt is being accepted"),
+      Kimera::Flag.build("--output FILE", :output, "Baseline file to write (default: .kimera-baseline.yml)"),
+      Kimera::FORCE_FLAG.with(help: "Replace an existing baseline file")
+    ]
+  )
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    __send__(command(argv.shift), argv)
+  rescue Kimera::UsageError => error
+    @errors.puts("kimera: #{error.message}")
+    1
+  end
+
+  private
+
+  def command(name) = COMMANDS.fetch(name) { raise(Kimera::UsageError, "usage: kimera baseline <create|review> ...") }
+
+  def create(argv)
+    options = { reason: nil, output: ".kimera-baseline.yml", force: false }
+    report, = CREATE.parse(argv, options)
+    check(report, options)
+    write(report, options[:output], options[:reason])
+  end
+
+  def check(report, options)
+    raise(Kimera::UsageError, "baseline create needs a report file") unless report
+    raise(Kimera::UsageError, "baseline create requires --reason TEXT") if options[:reason].to_s.strip.empty?
+    raise(Kimera::UsageError, "no such report: #{report}") unless File.file?(report)
+    output = options[:output]
+    overwrite(output) if File.exist?(output) && !options[:force]
+  end
+
+  def overwrite(output) = raise(Kimera::UsageError, "#{output} already exists (use --force to replace it)")
+
+  def write(report, output, reason)
+    ignored = survivors(report).map { |row| entry(row, reason) }
+    File.write(output, YAML.dump("format_version" => 1, "ignore" => ignored))
+    @io.puts("Created #{output} with #{ignored.size} accepted survivor(s).")
+    @io.puts("Add `baseline: #{output}` to .kimera.yml to apply it.")
+    0
+  end
+
+  def review(argv)
+    file = argv.shift
+    raise(Kimera::UsageError, "usage: kimera baseline review BASELINE.yml") unless file && argv.empty?
+    raise(Kimera::UsageError, "no such baseline: #{file}") unless File.file?(file)
+    list(file, Array((YAML.safe_load_file(file) || {})["ignore"]))
+  end
+
+  def list(file, entries)
+    @io.puts("#{entries.size} accepted mutant(s) in #{file}:")
+    entries.sort_by { |entry| [entry["file"], entry["line"], entry["label"]] }.each { |entry| @io.puts(line(entry)) }
+    0
+  end
+
+  def line(entry) = "  #{entry["file"]}:#{entry["line"]} [#{entry["label"]}] — #{entry["reason"]}"
+
+  def survivors(path)
+    Kimera::CLI::ReportFile.parse(path).fetch("results", []).select { |row| row["status"] == "survived" }
+  end
+
+  def entry(row, reason)
+    id, *fields = row.values_at("mutant_id", *ENTRY_KEYS)
+    ENTRY_KEYS.zip(fields).to_h { |key, value| [key, value || missing(key, id)] }.merge("reason" => reason)
+  end
+
+  def missing(key, id) = raise(Kimera::UsageError, "report is missing #{key} for mutant ##{id}")
+end

data/lib/kimera/cli/changed.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "argv"
+require_relative "run"
+
+class Kimera::CLI::Changed
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    args = argv.dup
+    args.unshift("--since", reference) unless Kimera::CLI::Argv.option?(args, "--since")
+    Kimera::CLI::Run.new(io: @io, errors: @errors).run(args)
+  end
+
+  private
+
+  def reference
+    %w[origin/main main].find { |name| branch?(name) } ||
+      raise(Kimera::UsageError, "cannot find origin/main or main; pass --since REF")
+  end
+
+  def branch?(name) = system("git", "rev-parse", "--verify", "--quiet", name, out: File::NULL, err: File::NULL)
+end

data/lib/kimera/cli/ci.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "argv"
+require_relative "run"
+
+class Kimera::CLI::CI
+  DEFAULTS = [
+    [%w[--max-survivors], %w[--max-survivors 0]],
+    [%w[--fail-on-no-coverage --no-fail-on-no-coverage], %w[--fail-on-no-coverage]],
+    [%w[--report], %w[--report tmp/kimera/report.json]],
+    [%w[--format], %w[--format github]]
+  ].freeze
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    args = DEFAULTS.reduce(argv.dup) { |given, (names, extra)| defaulted(given, names, extra) }
+    Kimera::CLI::Run.new(io: @io, errors: @errors).run(args)
+  end
+
+  private
+
+  def defaulted(args, names, extra) = Kimera::CLI::Argv.any?(args, names) ? args : args + extra
+end

data/lib/kimera/cli/completion.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Kimera
+end
+
+class Kimera::CLI
+end
+
+class Kimera::CLI::Completion
+  SCRIPTS = {
+    "bash" => "_kimera() { COMPREPLY=( $(compgen -W '%s' -- \"${COMP_WORDS[1]}\") ); }\ncomplete -F _kimera kimera",
+    "zsh" => "#compdef kimera\n_arguments '1:command:(%s)'",
+    "fish" => "complete -c kimera -f -a '%s'"
+  }.freeze
+  SHELLS = SCRIPTS.keys.freeze
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    shell = argv.first
+    return usage unless SHELLS.include?(shell) && argv.size == 1
+    @io.puts(script(shell))
+    0
+  end
+
+  private
+
+  def usage
+    @errors.puts("kimera: usage: kimera completion <#{SHELLS.join("|")}>")
+    1
+  end
+
+  def script(shell) = format(SCRIPTS.fetch(shell), Kimera::CLI::COMMAND_NAMES.join(" "))
+end

data/lib/kimera/cli/doctor.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../error"
+require_relative "../scope/config"
+require_relative "../scope/file_set"
+require_relative "flag"
+
+class Kimera::CLI::Doctor
+  OPTIONS = Kimera::FlagTable.new(
+    banner: "Usage: kimera doctor [--check-baseline]",
+    flags: [
+      Kimera::Flag.build("--check-baseline", :check_baseline, "Run the configured test suite and verify it is green")
+    ]
+  )
+
+  FRAMEWORK_FEATURES = { "rspec" => "rspec/core", "minitest" => "minitest" }.freeze
+
+  def initialize(io: $stdout, errors: $stderr, root: ".")
+    @io = io
+    @errors = errors
+    @root = root
+  end
+
+  def run(argv)
+    options = { check_baseline: false }
+    OPTIONS.parse(argv, options)
+    verdict(checks(Kimera::Config.root(root: @root), options))
+  rescue Kimera::UsageError => error
+    usage(error)
+  end
+
+  private
+
+  def usage(error)
+    @errors.puts("kimera: #{error.message}")
+    1
+  end
+
+  def checks(config, options)
+    all = [configuration(config), framework(config), sources(config), tests(config), git, rails]
+    options[:check_baseline] ? all << baseline(config) : all
+  end
+
+  def verdict(checks)
+    checks.each { |status, text| @io.puts("#{status} #{text}") }
+    failed = checks.count { |status,| status == "✗" }
+    return 0 if failed.zero?
+    @errors.puts("kimera: doctor found #{failed} blocking issue(s)")
+    1
+  end
+
+  def configuration(config)
+    path = File.join(@root, Kimera::Config::DEFAULT_PATH)
+    return ["!", "Configuration: none found; run `kimera init`"] unless File.file?(path)
+    ["✓", "Configuration: #{Kimera::Config::DEFAULT_PATH} (#{config.fetch(:framework, "rspec")})"]
+  end
+
+  def framework(config)
+    name = config.fetch(:framework, "rspec").to_s
+    feature = FRAMEWORK_FEATURES.fetch(name) { return ["✗", "Framework: unknown #{name}; use rspec or minitest"] }
+    return ["✓", "Framework: #{name} is installed"] if Gem.find_files(feature).any?
+    ["✗", "Framework: #{name} is not in this bundle; fix framework: in .kimera.yml or add it to the Gemfile"]
+  end
+
+  def sources(config)
+    count = glob(config.fetch(:paths, Kimera::FileSet::DEFAULT_GLOBS)).size
+    found(count, "Source scope: #{count} Ruby files", "Source scope: no Ruby files found; fix paths: in .kimera.yml")
+  end
+
+  def tests(config)
+    count = test_files(config).size
+    found(count, "Test discovery: #{count} files", "Test discovery: no test files found; fix tests: in .kimera.yml")
+  end
+
+  def found(count, present, absent) = count.zero? ? ["✗", absent] : ["✓", present]
+
+  def git
+    return ["✓", "Git: incremental runs are available"] if File.directory?(File.join(@root, ".git"))
+    ["!", "Git: not a repository; `kimera changed` is unavailable"]
+  end
+
+  def rails
+    return ["!", "Rails detected: verify parallel database isolation before using --jobs > 1"] if rails?
+    ["✓", "Runtime: no Rails-specific parallel setup required"]
+  end
+
+  def rails? = File.file?(File.join(@root, "config", "application.rb"))
+
+  def baseline(config)
+    output, status = Open3.capture2e(*command(config), chdir: @root)
+    return ["✓", "Baseline: configured test suite is green"] if status.success?
+    ["✗", "Baseline: #{summary(output)} (fix it, then rerun `kimera doctor --check-baseline`)"]
+  rescue Errno::ENOENT
+    ["✗", "Baseline: Bundler is unavailable; run your test suite, then retry"]
+  end
+
+  def command(config)
+    files = test_files(config)
+    minitest?(config) ? ["bundle", "exec", "ruby", "-Itest", *files] : ["bundle", "exec", "rspec", *files]
+  end
+
+  def summary(output)
+    output.lines.reverse.find { |line| line.match?(/\d+ failures?|\d+ examples?|failed/i) }&.strip ||
+      "test command failed"
+  end
+
+  def minitest?(config) = config.fetch(:framework, "rspec") == "minitest"
+
+  def test_files(config) = glob(config.fetch(:tests, tests_for(config)))
+
+  def tests_for(config) = minitest?(config) ? ["test/**/*_test.rb"] : ["spec/**/*_spec.rb"]
+
+  def glob(patterns) = Array(patterns).flat_map { |pattern| Dir.glob(File.join(@root, pattern)) }.uniq
+end

data/lib/kimera/cli/flag.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../error"
+
+module Kimera
+  Flag =
+    Data.define(:switch, :key, :help, :type, :collect) do
+      def self.build(switch, key, help, type: nil, collect: false)
+        new(switch: switch, key: key, help: help, type: type, collect: collect)
+      end
+
+      def define(parser, options)
+        parser.on(*signature) { |value| store(options, value) }
+      end
+      private
+      def signature = [*switch, type, help].compact
+
+      def store(options, value)
+        collect ? options[key] << value : options[key] = value
+      end
+    end
+
+  FlagTable =
+    Data.define(:banner, :flags) do
+      def parse(argv, options)
+        build(options).parse(argv)
+      rescue OptionParser::ParseError => error
+        raise(UsageError, "#{error.message}\n#{banner}")
+      end
+
+      def build(options)
+        OptionParser.new do |parser|
+          parser.banner = banner
+          flags.each { |flag| flag.define(parser, options) }
+        end
+      end
+
+      def keys = flags.map(&:key)
+    end
+
+  FORCE_FLAG = Flag.build("--force", :force, "Replace an existing file")
+  CONFIG_FLAG = Flag.build("--config FILE", :config, "Load config (default: .kimera.yml)")
+  REGISTRY_FLAG = Flag.build("--registry FILE", :registry, "Load registry JSON instead of building")
+  REQUIRE_FLAG = Flag.build(
+    "--require FILE", :require,
+    "Load a Ruby file before scanning, for custom operators (repeatable)",
+    collect: true
+  )
+  OPERATORS_FLAG = Flag.build(
+    "--operators a,b,c", :operators,
+    "Operator keys, or 'all'/'rails' (default: conservative core)",
+    type: Array
+  )
+end

data/lib/kimera/cli/help_text.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../scope/file_set"
+require_relative "../version"
+
+module Kimera
+  module HelpText
+    HELP = <<~HELP.freeze
+      kimera #{Kimera::VERSION} -- schemata-based mutation testing for Ruby
+      (every mutant is compiled into one guarded source tree, so the suite
+      loads once, not once per mutant)
+
+      Usage: kimera <command> [options]
+
+      Start here:
+        init                  Detect this project and create .kimera.yml
+        doctor                Validate source/test discovery and runtime safety
+        run [paths...]        Run mutation tests locally
+        changed [paths...]    Mutate only code changed since origin/main (or main)
+        ci [paths...]         Strict CI gate; writes a report artifact
+
+      Investigate:
+        report REPORT.json    Filter a saved report (survivors, uncovered, errors)
+        mutant ID --report R  Show one mutant in full detail
+        registry [paths...]   Inspect what Kimera would mutate
+        synthesize [paths...] Write schemata sources for inspection
+
+      Setup:
+        baseline ...          Create or review a baseline of accepted survivors
+        completion SHELL      Print Bash, Zsh, or Fish completion setup
+        skill                 Print the guide for AI agents running Kimera
+        version               Print version
+        help                  Show this help
+
+      With no paths, defaults to: #{Kimera::FileSet::DEFAULT_GLOBS.join(", ")}
+
+      Exit codes: 0 ok, 1 usage or setup error, 2 gate failed (run)
+
+      Examples:
+        kimera init && kimera doctor
+        kimera changed --report tmp/kimera/report.json
+        kimera report tmp/kimera/report.json --status no_coverage
+    HELP
+  end
+end

data/lib/kimera/cli/init.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "etc"
+require "yaml"
+require_relative "../error"
+require_relative "../scope/config"
+require_relative "../scope/file_set"
+require_relative "flag"
+
+class Kimera::CLI::Init
+  OPTIONS = Kimera::FlagTable.new(
+    banner: "Usage: kimera init [options]",
+    flags: [
+      Kimera::FORCE_FLAG.with(help: "Replace an existing .kimera.yml"),
+      Kimera::Flag.build("--dry-run", :dry_run, "Print the detected configuration without writing it")
+    ]
+  )
+
+  HELPERS = %w[spec/spec_helper.rb spec/rails_helper.rb spec/helper.rb test/test_helper.rb test/helper.rb].freeze
+  AGENT_POINTER = "Mutation testing: before running kimera or triaging its results, read `bundle exec kimera skill`.\n"
+
+  def initialize(io: $stdout, errors: $stderr, root: ".")
+    @io = io
+    @errors = errors
+    @root = root
+  end
+
+  def run(argv)
+    options = { force: false, dry_run: false }
+    OPTIONS.parse(argv, options)
+    options[:dry_run] ? preview : write(options)
+  rescue Kimera::UsageError => error
+    usage(error)
+  end
+
+  private
+
+  def usage(error)
+    @errors.puts("kimera: #{error.message}")
+    1
+  end
+
+  def preview
+    @io.write(YAML.dump(detected))
+    0
+  end
+
+  def write(options)
+    path = File.join(@root, Kimera::Config::DEFAULT_PATH)
+    overwrite(path) if File.exist?(path) && !options[:force]
+    File.write(path, YAML.dump(detected))
+    announce(*signpost)
+  end
+
+  def overwrite(path) = raise(Kimera::UsageError, "#{path} already exists (use --force to replace it)")
+
+  def signpost
+    path = File.join(@root, "AGENTS.md")
+    existing = File.file?(path) ? File.read(path) : ""
+    return [] if existing.include?("kimera skill")
+    File.write(path, pointed(existing))
+    ["Pointed AI agents to `kimera skill` in AGENTS.md."]
+  end
+
+  def pointed(text) = [text.rstrip, AGENT_POINTER].reject(&:empty?).join("\n\n")
+
+  def announce(*notes)
+    @io.puts("Created #{Kimera::Config::DEFAULT_PATH} for #{framework}.", *notes, "Next: kimera doctor")
+    0
+  end
+
+  def detected
+    Kimera::Config.document(
+      framework: framework, paths: sources, tests: tests,
+      jobs: [Etc.nprocessors, 8].min, max_survivors: 0, max_errors: 0, fail_on_no_coverage: false
+    )
+  end
+
+  def framework = @_framework ||= declared || layout
+
+  def declared
+    return "rspec" if File.file?(File.join(@root, ".rspec"))
+    helper = HELPERS.map { |path| File.join(@root, path) }.find { |path| File.file?(path) }
+    helper && framework_named_in(File.read(helper))
+  end
+
+  def framework_named_in(text)
+    return "rspec" if text.match?(/\bRSpec\b|require\s*\(?\s*["']rspec/)
+    "minitest" if text.match?(/minitest/i)
+  end
+
+  def layout
+    File.directory?(File.join(@root, "test")) && !File.directory?(File.join(@root, "spec")) ? "minitest" : "rspec"
+  end
+
+  def sources
+    paths = %w[app/**/*.rb lib/**/*.rb].select { |glob| Dir.glob(File.join(@root, glob)).any? }
+    paths.empty? ? Kimera::FileSet::DEFAULT_GLOBS : paths
+  end
+
+  def tests
+    globs = framework == "minitest" ? %w[test/**/*_test.rb spec/**/*_spec.rb] : %w[spec/**/*_spec.rb]
+    [globs.find { |glob| Dir.glob(File.join(@root, glob)).any? } || globs.first]
+  end
+end

data/lib/kimera/cli/mutant.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "flag"
+require_relative "report_file"
+require_relative "run"
+require_relative "survivors"
+
+class Kimera::CLI::Mutant
+  OPTIONS = Kimera::FlagTable.new(
+    banner: "Usage: kimera mutant ID --report REPORT.json",
+    flags: [
+      Kimera::Flag.build("--report FILE", :report, "Report generated by kimera run"),
+      Kimera::Flag.build("--rerun", :rerun, "Re-evaluate only this mutant in the current project")
+    ]
+  )
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    options = { report: nil, rerun: false }
+    id, = OPTIONS.parse(argv, options)
+    show(identify(id, options), options)
+  rescue Kimera::UsageError => error
+    usage(error)
+  end
+
+  private
+
+  def usage(error)
+    @errors.puts("kimera: #{error.message}")
+    1
+  end
+
+  def identify(id, options)
+    raise(Kimera::UsageError, "mutant ID is required") unless id
+    raise(Kimera::UsageError, "--report REPORT.json is required") unless options[:report]
+    Integer(id)
+  rescue ArgumentError
+    raise(Kimera::UsageError, "mutant ID must be an integer")
+  end
+
+  def show(id, options)
+    report = options[:report]
+    return rerun(id, report) if options[:rerun]
+    Kimera::CLI::Survivors.new(io: @io, errors: @errors).run([report, "--id", id.to_s])
+  end
+
+  def rerun(id, report)
+    document = Kimera::CLI::ReportFile.parse(report)
+    row = locate(document, id)
+    @io.puts("Re-running mutant ##{id} in #{row["file"]}.")
+    Kimera::CLI::Run.new(io: @io, errors: @errors).run(arguments_for(row, id, provenance(document)))
+  end
+
+  def locate(document, id)
+    row = document.fetch("results", []).find { |result| result["mutant_id"] == id }
+    raise(Kimera::UsageError, "no mutant ##{id} in this report") unless row
+    raise(Kimera::UsageError, "mutant ##{id} has no source file") unless row["file"]
+    row
+  end
+
+  def provenance(document)
+    document["run"] ||
+      raise(Kimera::UsageError, "report has no run provenance; rerun with a report created by this Kimera version")
+  end
+
+  def arguments_for(row, id, settings)
+    [row.fetch("file"), "--focus", id.to_s, "--framework", settings.fetch("framework", "rspec")]
+      .push("--source-root", settings["source_root"])
+      .concat(Array(settings["tests"]).flat_map { |glob| ["--tests", glob] })
+      .push("--operators", Array(settings["operators"]).join(","))
+      .concat(modes(settings))
+  end
+
+  def modes(settings)
+    [settings["coverage"] == false ? "--no-coverage" : nil, settings["isolated"] ? "--isolated" : nil].compact
+  end
+end

data/lib/kimera/cli/report_file.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../error"
+
+module Kimera
+end
+
+class Kimera::CLI
+end
+
+module Kimera::CLI::ReportFile
+  module_function
+
+  def parse(path)
+    JSON.parse(File.read(path))
+  rescue JSON::ParserError => error
+    raise(Kimera::UsageError, "unreadable report #{path}: #{error.message}")
+  end
+end