saboteur 0.3.0 → 0.5.0

data/lib/saboteur/help.rb

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
-require "json"
 require_relative "config"
 
 module Saboteur
@@ -18,20 +17,20 @@ module Saboteur
     DOCUMENTATION = "https://github.com/vamsipavanmahesh/saboteur"
 
     EXIT_CODE_MEANINGS = {
-      0 => "Success. Without --threshold: no unignored survivors. With --threshold: the score is at or above " \
-           "it, even if mutants survived.",
+      0 => "Success. Without --threshold: no unignored survivors, and at most half of the executed mutants " \
+           "errored. With --threshold: the score is at or above it, even if mutants survived.",
       1 => "Without --threshold: at least one mutant survived and is not on the ignore list. With --threshold " \
            "(survivors alone no longer fail the run): the score is below it, or no mutant was tested so " \
-           "there is no score.",
-      2 => "Usage or configuration error: fix the command or .saboteur.yml. A replay --id that matches no " \
+           "there is no score. Also more timeout or errored mutants than --max-timeouts or --max-errors allow.",
+      2 => "Usage or configuration error: fix the command or config/saboteur.rb. A replay --id that matches no " \
            "mutant is only found after the target has booted. A named source or test file that does not exist.",
-      3 => "Tool error: saboteur could not finish, or every executed mutant errored. With --threshold, " \
-           "also any errored or resource-limited mutant."
+      3 => "Tool error: saboteur could not finish, or more than half of the executed mutants errored (such " \
+           "a run tested almost nothing). With --threshold, also any errored or resource-limited mutant."
     }.freeze
 
     DOCTOR_EXIT_CODE_MEANINGS = {
       0 => "Healthy: the environment checks passed and the baseline passed twice in the same order.",
-      2 => "Usage or configuration error: fix the command or .saboteur.yml.",
+      2 => "Usage or configuration error: fix the command or config/saboteur.rb.",
       3 => "A check failed: the target did not boot, or the baseline failed or changed between runs."
     }.freeze
 
@@ -43,7 +42,8 @@ module Saboteur
                      "tests that cover each change, and reports survivors (changes no test noticed). Source files or " \
                      "directories after run replace include and exclude; --test limits the specs that run; " \
                      "--threshold PERCENT replaces the survivor check: exit 0 when the score is at or above " \
-                     "PERCENT, exit 1 when it is below.",
+                     "PERCENT, exit 1 when it is below. Inline comment syntax: " \
+                     '# saboteur:disable-line [operator ...] reason="...". A reason is required.',
         takes_options: true,
         exit_codes: EXIT_CODE_MEANINGS,
         examples: [
@@ -53,19 +53,43 @@ module Saboteur
           ["Replay one mutant by the digest printed next to a survivor", "saboteur run --id 1a2b3c4d5e6f7a8b"],
           ["Mutate named files against named specs, skipping the whole-suite coverage run",
            "saboteur run lib/a.rb lib/b.rb --test spec/a_spec.rb --test spec/b_spec.rb"],
-          ["CI gate: exit 1 when the score is below 90 percent", "saboteur run --threshold 90"]
+          ["CI gate: exit 1 when the score is below 90 percent", "saboteur run --threshold 90"],
+          ["AI agent: bounded JSON summary and strict exit codes", "saboteur run --agent --since origin/main"]
         ]
       ),
       Command.new(
         name: "doctor",
-        summary: "Check the environment and run the baseline twice, without mutating anything",
-        description: "Boots the target like a run, checks runtime, coverage and boot files, then runs your " \
-                     "suite twice in the same order with one seed and reports whether both runs passed. " \
-                     "It never mutates anything.",
+        summary: "Check the environment, and with --suite run the baseline twice, without mutating anything",
+        description: "Boots the target like a run and checks runtime, coverage and boot files. With --suite " \
+                     "it also runs your suite twice in the same order with one seed and reports whether both " \
+                     "runs passed; --test PATH limits those runs to some specs. It never mutates anything.",
         takes_options: true,
         exit_codes: DOCTOR_EXIT_CODE_MEANINGS,
         examples: [["Check the setup before the first run", "saboteur doctor"],
-                   ["Use another config file and seed", "saboteur doctor --config ci.yml --seed 7"]]
+                   ["Also run the unchanged suite twice", "saboteur doctor --suite --seed 7"],
+                   ["Run only some specs twice", "saboteur doctor --test spec/models"]]
+      ),
+      Command.new(
+        name: "baseline",
+        summary: "Check, propose or accept a fresh opt-in survivor baseline",
+        description: "Check runs every mutant fresh and reports new, changed or unmatched accepted survivors. " \
+                     "Propose writes a proposal with private local execution evidence. Edit only survivor reasons; " \
+                     "accept verifies current inputs and publishes it. No scores or execution are suppressed. " \
+                     "With --epsilon POINTS, check also fails when the score drops more than POINTS percentage " \
+                     "points below the accepted baseline's score. " \
+                     "Only whole or subject scope; no diff, replay, incremental reuse or score threshold.",
+        takes_options: true,
+        exit_codes: { 0 => "Clean check, proposal written or accepted.",
+                      1 => "New, changed or unmatched survivors, or a score drop beyond --epsilon.",
+                      2 => "Invalid configuration, incompatible baseline or rejected acceptance.",
+                      3 => "Incomplete execution or tool failure." },
+        examples: [["Prepare a reasoned proposal",
+                    "saboteur baseline propose --baseline baseline.json --proposal proposal.json"],
+                   ["Publish reviewed reasons",
+                    "saboteur baseline accept --baseline baseline.json --proposal proposal.json"],
+                   ["Check fresh outcomes", "saboteur baseline check --baseline baseline.json"],
+                   ["Also fail on a score drop of more than 2 points",
+                    "saboteur baseline check --baseline baseline.json --epsilon 2"]]
       ),
       Command.new(
         name: "version",
@@ -83,12 +107,25 @@ module Saboteur
         takes_options: false,
         exit_codes: nil,
         examples: [["Show everything", "saboteur help"], ["Show one command", "saboteur help run"]]
+      ),
+      Command.new(
+        name: "agent-skill",
+        summary: "Print instructions for AI coding agents to paste into AGENTS.md or CLAUDE.md",
+        description: "Prints a short Markdown block that tells an agent when to run saboteur, how to read " \
+                     "`saboteur run --agent`, and how to handle survivors.",
+        takes_options: false,
+        exit_codes: nil,
+        examples: [["Add the agent instructions to your repo", "saboteur agent-skill >> AGENTS.md"]]
       )
     ].freeze
 
+    AGENT_EXIT_CODES = "  With --agent the codes are stricter: 0 only when the run was complete and clean; " \
+                       "1 survivors to review;\n  2 usage or config error; 3 incomplete (no coverage, caps, errors, " \
+                       "nothing selected) or tool failure."
+
     FILES = [
-      [".saboteur.yml", "Settings. Command line options override it."],
-      [".saboteur-ignore.yml", "Accepted survivors: entries with subject, mutation (digest) and a required reason."],
+      ["config/saboteur.rb", "Settings as Ruby (Saboteur.configure). Command line options override it."],
+      ["config/saboteur_ignore.rb", "Accepted survivors: mutation digests with subject and a required reason."],
       [".saboteur/report.json", "Stryker mutation-testing-report-schema JSON (--json changes the path)."],
       [".saboteur/report.html", "Self-contained HTML report (--html changes the path)."],
       [".saboteur/", "Cache: coverage map and incremental verdicts. Safe to delete."]
@@ -169,18 +206,21 @@ module Saboteur
     def exit_codes_section(codes, command_name = nil)
       rows = codes.map { |code, meaning| "  #{code}  #{meaning}" }
       title = command_name ? "EXIT CODES (saboteur #{command_name})" : "EXIT CODES"
-      "#{title}\n#{rows.join("\n")}\n"
+      note = codes.equal?(EXIT_CODE_MEANINGS) ? "#{AGENT_EXIT_CODES}\n" : ""
+      "#{title}\n#{rows.join("\n")}\n#{note}"
     end
 
     def config_section
-      rows = Config::DEFAULTS.map { |key, value| "  #{key}: #{describe_default(value)}" }
-      intro = "Every key with its default value, as YAML. Unknown keys are an error."
-      "CONFIG FILE (.saboteur.yml)\n#{intro}\n#{rows.join("\n")}\n"
+      rows = Config::DEFAULTS.map { |key, value| "  c.#{key} = #{describe_default(value)}" }
+      intro = "Every setting with its default value, as a Ruby assignment. Unknown settings are an error."
+      "CONFIG FILE (config/saboteur.rb)\n#{intro}\n#{rows.join("\n")}\n"
     end
 
-    # Valid YAML (JSON flow style), so a copied line keeps the default's meaning.
+    # Ruby literals, so a copied line loads as the same value: inspect prints
+    # nil as "nil" (JSON would print null, which is not Ruby) and quotes
+    # strings and arrays the way Ruby reads them back.
     def describe_default(value)
-      JSON.generate(value)
+      value.inspect
     end
 
     def files_section

data/lib/saboteur/ignore_list.rb

@@ -1,40 +1,94 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
-require "yaml"
-
 module Saboteur
-  # Survivors the team has accepted. YAML list of entries:
+  # Entry point used by config/saboteur_ignore.rb.
+  def self.ignore
+    collector = IgnoreList.current_collector
+    raise "Saboteur.ignore is only valid while config/saboteur_ignore.rb loads" unless collector
+
+    yield collector
+    collector
+  end
+
+  # Survivors the team has accepted. config/saboteur_ignore.rb declares them:
   #
-  #   - subject: "Person#adult?"
-  #     mutation: "1a2b3c4d5e6f7a8b"   # digest shown next to each survivor
-  #     reason: "equivalent: age is always an integer"
+  #   Saboteur.ignore do |i|
+  #     i.mutation "1a2b3c4d5e6f7a8b",
+  #                subject: "Person#adult?",
+  #                reason: "equivalent: age is always an integer"
+  #   end
   #
   # reason is mandatory; a file with a missing or blank reason does not load.
   class IgnoreList
     Entry = Data.define(:subject, :mutation, :reason)
 
+    # Collects the entries a saboteur_ignore.rb file declares.
+    class Collector
+      attr_reader :entries
+
+      def initialize
+        @entries = []
+      end
+
+      def mutation(digest = nil, subject: nil, reason: nil)
+        line = caller_locations(1, 1).first.lineno
+        values = { "subject" => subject, "mutation" => digest, "reason" => reason }
+        missing = values.select { |_, value| value.to_s.strip.empty? }.keys
+        raise ConfigError, "#{line}: entry is missing #{missing.join(', ')}" if missing.any?
+
+        @entries << Entry.new(
+          subject: subject.to_s.strip,
+          mutation: digest.to_s.strip,
+          reason: reason.to_s.strip
+        )
+      end
+    end
+
     attr_reader :entries
 
+    # The collector is process-global on purpose: the ignore file calls the
+    # top-level Saboteur.ignore, which must reach the load in progress.
+    # Loads are therefore serialized - never load two ignore files at once.
     def self.load(path)
       return new([]) unless path && File.file?(path)
 
-      data = YAML.safe_load_file(path) || []
-      raise ConfigError, "#{path}: expected a list of entries" unless data.is_a?(Array)
+      @collector = Collector.new
+      Kernel.load(path)
+      new(@collector.entries)
+    rescue ConfigError => e
+      raise ConfigError, "#{path}:#{e.message}"
+    rescue NoMethodError => e
+      raise ConfigError, unknown_directive_message(path, e) if e.receiver.is_a?(Collector)
+
+      # A typo'd call outside the collector: same treatment as a bare
+      # constant, or the raw NoMethodError points at our internals.
+      raise ConfigError, name_error_message(path, e)
+    rescue SyntaxError, LoadError => e
+      raise ConfigError, "#{path}: #{e.message.lines.first.to_s.chomp}"
+    rescue NameError => e
+      raise ConfigError, name_error_message(path, e)
+    ensure
+      @collector = nil
+    end
 
-      new(data.each_with_index.map { |raw, index| parse_entry(raw, path, index) })
-    rescue Psych::SyntaxError => e
-      raise ConfigError, "#{path}: #{e.message}"
+    def self.unknown_directive_message(path, error)
+      line = error.backtrace_locations.find { |loc| loc.path == path }&.lineno
+      "#{path}:#{line}: unknown directive #{error.name.to_s.inspect} - " \
+        'declare entries with mutation "<digest>", subject:, reason:'
     end
 
-    def self.parse_entry(raw, path, index)
-      raise ConfigError, "#{path}: entry #{index + 1} is not a mapping" unless raw.is_a?(Hash)
+    def self.name_error_message(path, error)
+      line = error.backtrace_locations&.find { |loc| loc.path == path }&.lineno
+      "#{path}:#{line}: #{error.message.lines.first.to_s.chomp} " \
+        "- this file loads before the app boots; use plain Ruby or ENV"
+    end
 
-      values = %w[subject mutation reason].to_h { |key| [key, raw[key].to_s.strip] }
-      missing = values.select { |_, value| value.empty? }.keys
-      raise ConfigError, "#{path}: entry #{index + 1} is missing #{missing.join(', ')}" if missing.any?
+    private_class_method :unknown_directive_message, :name_error_message
 
-      Entry.new(subject: values["subject"], mutation: values["mutation"], reason: values["reason"])
+    # The Collector Saboteur.ignore hands to the file being loaded.
+    def self.current_collector
+      @collector
     end
 
     def initialize(entries)
@@ -42,6 +96,11 @@ module Saboteur
       @index = entries.to_h { |entry| [[entry.subject, entry.mutation], entry] }
     end
 
+    # True when this result is a survivor the list accepts.
+    def accepts?(result)
+      result.survived? && @index.key?([result.subject.id, result.digest])
+    end
+
     # Marks matching survivors as ignored. Returns warnings for stale entries:
     # entries whose subject was examined but whose mutation no longer exists.
     def apply(results)

data/lib/saboteur/inline_suppression.rb

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require "shellwords"
+require_relative "mutation_source/operator_registry"
+
+module Saboteur
+  # Only real Ruby comments can suppress edits, never text inside a string.
+  class InlineSuppression
+    Directive = Data.define(:line, :operators, :reason)
+
+    def initialize(file, source)
+      @file = file
+      @directives = Prism.parse(source).comments.filter_map { |comment| parse(comment) }
+    end
+
+    # Preserve ordinary comment/formatting skips, but treat directives as
+    # selection inputs. Relative lines distinguish which code they suppress.
+    def signature(subject)
+      @directives.select { |entry| subject.contains_line?(entry.line) }.map do |entry|
+        [entry.line - subject.start_line, entry.operators.sort, entry.reason]
+      end
+    end
+
+    def reason(subject, mutation)
+      mutation.edits.each do |edit|
+        line = subject.line_of(edit.start_byte)
+        directive = @directives.find do |entry|
+          entry.line == line && (entry.operators.empty? || entry.operators.include?(mutation.operator))
+        end
+        return directive if directive
+      end
+      nil
+    end
+
+    private
+
+    def parse(comment)
+      text = comment.location.slice.sub(/\A#\s*/, "")
+      return nil unless text.start_with?("saboteur:disable-line")
+
+      line = comment.location.start_line
+      tokens = Shellwords.split(text)
+      fail_at(line, "expected saboteur:disable-line") unless tokens.shift == "saboteur:disable-line"
+      reasons, operators = tokens.partition { |token| token.start_with?("reason=") }
+      reason, = reasons
+      fail_at(line, "one nonblank reason=\"...\" is required") unless
+        reasons.size == 1 && !reason.delete_prefix("reason=").strip.empty?
+      validate_operators(operators, line)
+      Directive.new(line: line, operators: operators, reason: reason.delete_prefix("reason="))
+    rescue ArgumentError => e
+      fail_at(line, "invalid suppression: #{e.message}")
+    end
+
+    def validate_operators(operators, line)
+      unknown = operators - MutationSource::OperatorRegistry::DESCRIPTIONS.keys
+      fail_at(line, "unknown operators: #{unknown.join(', ')}") unless unknown.empty?
+    end
+
+    def fail_at(line, message)
+      raise ConfigError, "#{@file}:#{line}: #{message}"
+    end
+  end
+end

data/lib/saboteur/install.rb

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Saboteur
+  # Writes the Rails starter files: config/saboteur.rb, bin/saboteur and a
+  # .gitignore entry. Plain Ruby so it runs and tests without Rails; the
+  # `rails generate saboteur:install` generator is a thin wrapper over it.
+  # Existing files are never overwritten unless force is set.
+  class Install
+    CONFIG = <<~RUBY
+      # saboteur configuration for a Rails + RSpec app. CLI flags override this file.
+      Saboteur.configure do |c|
+        c.include = ["app/**/*.rb"]
+        # Empty base classes: nothing useful to mutate.
+        c.exclude = [
+          "app/models/application_record.rb",
+          "app/controllers/application_controller.rb",
+          "app/jobs/application_job.rb",
+          "app/mailers/application_mailer.rb",
+        ]
+        c.require = ["./config/environment"] # boots the app before specs load
+        c.rails = true                       # reconnect ActiveRecord after fork, per-worker databases
+        c.jobs = 4                           # parallel workers; use 1 if your specs share external state
+      end
+    RUBY
+
+    BIN = <<~RUBY
+      #!/usr/bin/env ruby
+      # frozen_string_literal: true
+
+      ENV["RAILS_ENV"] ||= "test"
+      require "bundler/setup"
+      load Gem.bin_path("saboteur", "saboteur")
+    RUBY
+
+    IGNORE_ENTRY = ".saboteur/"
+
+    GEMFILE_HINT = <<~TEXT
+      Add saboteur to your Gemfile if it is not there yet:
+
+        group :test do
+          gem "saboteur", require: false
+        end
+
+      Then run it with SimpleCov off for the run, for example:
+
+        bin/saboteur run --since origin/main
+    TEXT
+
+    Result = Data.define(:status, :path)
+
+    def initialize(root: Dir.pwd, force: false)
+      @root = File.expand_path(root)
+      @force = force
+    end
+
+    # Returns the list of Results (:created, :overwritten, :skipped, :appended, :unchanged).
+    def call
+      [write("config/saboteur.rb", CONFIG), write("bin/saboteur", BIN, mode: 0o755), gitignore]
+    end
+
+    # Printed after install; the Gemfile is never edited.
+    def gemfile_hint
+      gemfile = File.join(@root, "Gemfile")
+      return nil if File.file?(gemfile) && File.read(gemfile).match?(/^\s*gem\s+["']saboteur["']/)
+
+      GEMFILE_HINT
+    end
+
+    private
+
+    # Never writes or chmods through a symlink: not the file itself, and not a
+    # symlinked directory above it (bin -> elsewhere). Without force the file is
+    # skipped; with force the link is removed and replaced by a real file or
+    # directory inside the project, and the old target is left alone.
+    def write(relative, content, mode: nil)
+      path = File.join(@root, relative)
+      link = symlink_component(relative)
+      existed = present?(path)
+      return Result.new(:skipped, relative) if (existed || link) && !@force
+
+      File.delete(link) if link
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+      File.chmod(mode, path) if mode
+      Result.new(existed ? :overwritten : :created, relative)
+    end
+
+    # The first symlink on the way from the project root to the file, if any.
+    def symlink_component(relative)
+      current = @root
+      relative.split("/").each do |part|
+        current = File.join(current, part)
+        return current if File.symlink?(current)
+      end
+      nil
+    end
+
+    # A dangling symlink does not "exist" but is not free to write either.
+    def present?(path)
+      File.exist?(path) || File.symlink?(path)
+    end
+
+    def gitignore
+      path = File.join(@root, ".gitignore")
+      link = symlink_component(".gitignore")
+      return Result.new(:skipped, ".gitignore") if link && !@force
+
+      current = File.file?(path) ? File.read(path) : ""
+      listed = listed?(current)
+      return Result.new(:unchanged, ".gitignore") if listed && !link
+
+      File.delete(link) if link
+      File.write(path, "#{current}#{missing_entry(current, listed)}")
+      Result.new(link ? :overwritten : :appended, ".gitignore")
+    end
+
+    def listed?(text)
+      text.lines.map(&:strip).include?(IGNORE_ENTRY)
+    end
+
+    # What to append so .saboteur/ is on its own line; nothing if already there.
+    def missing_entry(current, listed)
+      return "" if listed
+
+      separator = current.empty? || current.end_with?("\n") ? "" : "\n"
+      "#{separator}#{IGNORE_ENTRY}\n"
+    end
+  end
+end

data/lib/saboteur/integration/base.rb

@@ -77,4 +77,5 @@ module Saboteur
   end
 end
 
+require_relative "focus_guard"
 require_relative "rspec"

data/lib/saboteur/integration/focus_guard.rb

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Integration
+    # Refuses a suite that a focus filter has narrowed without the user asking
+    # for it. With `filter_run_when_matching :focus`, one stray `fit` makes
+    # RSpec skip every other example. The baseline stays green and the score
+    # then describes only the focused examples, with no sign that the rest
+    # never ran.
+    #
+    # The test is a difference of two selections, both made by RSpec's own
+    # FilterManager#prune: the examples that run now, and the examples that
+    # would run if the stray focus rule were absent. Everything else RSpec
+    # decides stays the same in both, so it never counts as hidden: example
+    # selectors (`spec/a_spec.rb:12`) and their file-scoped priority,
+    # `--tag` filters named in rspec_args, exclusions, and the :if / :unless
+    # pruning of conditional examples.
+    class FocusGuard
+      LOCATION_KEYS = %i[locations ids].freeze
+
+      def initialize(world:, explicit_filter_keys:)
+        @world = world
+        @explicit_filter_keys = explicit_filter_keys
+      end
+
+      # Raises ConfigError naming the focused examples when the focus filter
+      # hides examples that would otherwise run.
+      def check!
+        return if stray_rules.empty?
+        return if hidden_examples.empty?
+
+        raise ConfigError, message
+      end
+
+      private
+
+      attr_reader :world
+
+      def filter_manager
+        world.filter_manager
+      end
+
+      # Inclusion rules the suite added itself, such as the :focus rule that
+      # `filter_run_when_matching :focus` installs once a fit exists.
+      def stray_rules
+        @stray_rules ||= begin
+          rules = filter_manager.inclusions.rules
+          rules.slice(*(rules.keys - LOCATION_KEYS - @explicit_filter_keys))
+        end
+      end
+
+      def running_examples
+        @running_examples ||= filter_manager.prune(world.all_examples)
+      end
+
+      # The selection RSpec would make without the stray rules.
+      def examples_without_stray_focus
+        manager = ::RSpec::Core::FilterManager.new
+        manager.exclusions.rules.replace(filter_manager.exclusions.rules)
+        manager.inclusions.rules.replace(filter_manager.inclusions.rules.except(*stray_rules.keys))
+        manager.prune(world.all_examples)
+      end
+
+      def hidden_examples
+        @hidden_examples ||= examples_without_stray_focus - running_examples
+      end
+
+      def focused_examples
+        focus = ::RSpec::Core::FilterRules.new(stray_rules)
+        running_examples.select { |example| focus.include_example?(example) }
+      end
+
+      def message
+        total = hidden_examples.size + running_examples.size
+        locations = focused_examples.map(&:location).uniq.first(5).join(", ")
+        "a focus filter (#{::RSpec::Core::FilterRules.new(stray_rules).description}) narrowed the suite: " \
+          "#{hidden_examples.size} of #{total} examples would not run, so the score would cover only the " \
+          "ones that do (#{locations}). Remove the focus, or pass --allow-focus to run the narrowed suite anyway."
+      end
+    end
+  end
+end