saboteur 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9d8e69906c1a27f726dea87fb72eae3a92a6dfc4e3d10a5fbe903c0f8cd4e38
-  data.tar.gz: f6c85551dd523d8926c3ac05313f1dc0edea86aa84d321a8b4e05d7f84ca4706
+  metadata.gz: 50217a40a53106f31413eb89d15146944e93d15a83de3d2670c028094ef956b3
+  data.tar.gz: 534b1a15255aa3dd4743eb6c5a813529f8b4460423858c4de6e61bc34e2a6c93
 SHA512:
-  metadata.gz: 8b4bddc7c4b7b621082a6ad986e49e3e4a113ae1100f4cfb18f6a649d6ac8f852da486f110bcb61da0af3d8f588c172970e1526454d857d7ca6fb1411bde2c48
-  data.tar.gz: 4b8ab1f9f45dd75506b7e5a388a85af5a2fa46cbe6b70bc885ef1dc615988e4ef01ca4815fe67b2f8fd62cb5aa07511bf733da8e4f21775e6325080f478f2f06
+  metadata.gz: 599ab18ac5ea974b823c6b84d35ac721ab40ceb902155145c9f87311834a767fc66e8c53c88e69a142f35825612a5799579648894eccb833db47b389b566e591
+  data.tar.gz: a1952882b5586fa3d846fb123f4700f5b5f0085d8c81dd129afeb4a08f3437da27550f93e7ac3aeb3a59ce682d26e7b31f200734c46da03105f254ac3fa2138d

data/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-14
+
+### Fixed
+- `saboteur doctor`'s boot-file check accepts `require` and `hooks`
+  paths with or without the `.rb` extension, so the README's
+  `c.require = ["./config/environment"]` quickstart no longer fails
+  the check (#257).
+
+### Added
+- `allow_db_hosts` config (#258): hosts you assert are disposable test
+  databases. The Rails integration's local-database check accepts them,
+  and its refusal names the setting. `saboteur doctor` surfaces the same
+  refusal, naming the remote hosts, and after a successful boot prints
+  each test database's host. `0.0.0.0` now counts as a local host: compose
+  setups write it into database URLs, and connecting to it reaches this
+  machine.
+- `--guess-tests` now maps files in packwerk packs (any directory with a
+  `package.yml`) to the spec inside the same pack, and maps
+  `app/controllers` files to `spec/requests` specs (`users_spec.rb` or
+  `users_controller_spec.rb`). It still names the changed files it could
+  not match (#259).
+- `script/preflight`: a local pre-review check on one exact base and head
+  (#210). It runs the protected-path scope check, sign-off, SPDX headers,
+  whitespace, RuboCop and the specs (fast or full mode), writes every harness
+  output through a symlink-safe writer under `tmp/preflight/`, and takes
+  check reports through harness-owned pipes rather than checkout paths.
+  It is not CI and a pass is not an approval.
+
+### Changed
+- All built-in operators now run by default, including `range`, `operator_assignment` and `condition_negation`, which were opt-in in 0.5.0. Use `--exclude-operators` (or `c.exclude_operators`) to omit operators, or `--operators` (or `c.operators`) to select a smaller set. Exclusions win; each CLI list replaces its matching config list. This changes the default mutation set: counts, runtime, survivors and scores may change. Review CI thresholds and survivor baselines before adopting the new results. To retain the 0.5.0 default operator set during migration: `bundle exec saboteur run --exclude-operators range,operator_assignment,condition_negation`. To clear an exclusion set in config from the CLI: `bundle exec saboteur run --exclude-operators ''`.
+- Breaking selection policy change: old `core`/`extended` tier names are refused with migration guidance. Policy version 2 binds effective operators and exclusions to cache/verdict identity, reports, score-history v2 and baseline evidence. Old baselines are incompatible and need a fresh reviewed proposal; unchanged mutation IDs stay stable.
+
 ## [0.5.0] - 2026-10-14
 
 ### Added

data/README.md

@@ -500,6 +500,13 @@ Doctor boots your app, checks the config and the test database host, and runs
 your suite twice before any mutation. Fix whatever it reports first. Turn
 SimpleCov off for the run if you use it.
 
+The database check refuses any test database whose host is not local
+(`localhost`, `127.0.0.1`, `::1`, `0.0.0.0` or a socket), so a remote
+database is never mutated by accident. `0.0.0.0` counts as local: compose
+setups write it into database URLs, and connecting to it reaches this
+machine. For another disposable test database host, assert it yourself:
+`c.allow_db_hosts = ["db.internal"]` in `config/saboteur.rb`.
+
 **4. Test what your branch changed**
 
 ```sh
@@ -885,6 +892,14 @@ details are in [docs/design.md](docs/design.md), prior art in
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Commits need a DCO `Signed-off-by` line.
 
+Before you ask for review, run the local preflight check on your exact head:
+
+```sh
+ruby script/preflight --base <full main sha> --head <full head sha> --base-ref main --mode full
+```
+
+It runs scope, sign-off, SPDX, full RuboCop and the specs, and writes a report under `tmp/preflight/`. A pass is not an approval; fast mode is partial. See [docs/preflight.md](docs/preflight.md).
+
 ## Acknowledgements
 
 Thanks to [Glomo](https://glomo.one) for providing the AI tokens used to build saboteur.
@@ -932,13 +947,30 @@ The builtin `endpoint_replacement` operator swaps explicit, no-argument `first`/
 
 JSON findings are ordered by a deterministic [review ranking](docs/survivor-ranking.md): coarse first, then covering-test count, edited-line impact and changed-line proximity, with file/line/digest ties. The terminal groups survivors by file, method and line first; the ranking only orders the survivors on one line, and every survivor is listed, in review mode too. Only consecutive survivors with matching evidence share a test/evidence block; repeated evidence after another group is printed again to keep that order. Ranking does not change scores or execution.
 
+Cache and baseline identities include the policy. Re-propose and review old survivor baselines with `baseline propose`; never auto-accept new survivors. Mutation digests for unchanged edits stay stable.
+
 ### Preview and choose operators
 
 `bundle exec saboteur run --dry-run` discovers source methods and generates candidates without booting the app, running tests, forking, or writing reports/caches. It honors `--since`, `--subject` and source arguments. It prints per-method counts and cap omissions. After a matching normal run, a cached estimate shows baseline covering-test work (cached original-test durations times planned mutants; it is not a bound on mutant runtime and excludes boot and fork costs). If any file cannot be parsed, the total is marked INCOMPLETE and no estimate is given.
 
 Trust boundary: `--dry-run` never boots the app or runs its tests, but custom `sources` entries (`path.rb:ClassName`) are still `require`d to generate candidates, so their code runs. Only preview with sources you trust.
 
-`bundle exec saboteur run --list-operators` lists every builtin name and description. `--operators arithmetic,comparison` or `c.operators = ["arithmetic", "comparison"]` selects names. Tiers are `core`, `extended`, and `all`; core contains the current default operators. Extended adds opt-in [`range`](docs/operators/range.md), [`operator_assignment`](docs/operators/operator_assignment.md), and [`condition_negation`](docs/operators/condition_negation.md). Empty/default selection keeps only core operators. Selection changes invalidate incremental verdict identity.
+`bundle exec saboteur run --list-operators` lists every builtin name and description. All builtin operators run by default, including [`range`](docs/operators/range.md), [`operator_assignment`](docs/operators/operator_assignment.md), and [`condition_negation`](docs/operators/condition_negation.md). `--operators arithmetic,comparison` or `c.operators = ["arithmetic", "comparison"]` still selects a subset; `all` selects every name. There is no opt-in tier. `--exclude-operators range,condition_negation` or `c.exclude_operators = ["range", "condition_negation"]` removes named operators from that selection; exclusion wins if a name is in both lists. An empty selection means all, while an empty exclusion means none. CLI lists replace their corresponding config lists. These controls apply to builtin operators, not custom source plugins. Selection and exclusions invalidate cached verdict identity and are carried into agent rerun/replay commands.
+
+
+All operators run unless you select a smaller set; exclusions always remove operators from that set.
+Repeated `--operators` or `--exclude-operators` flags use the last list, not a union.
+To re-enable an operator excluded in config: `bundle exec saboteur run --operators range --exclude-operators ''`.
+To keep the 0.5.0 default inventory: `bundle exec saboteur run --exclude-operators range,operator_assignment,condition_negation`.
+The old `core` and `extended` names now give a migration error, not a changed selection in disguise.
+An empty effective selection is a usage error before boot. `--list-operators` loads current config and shows on/off plus examples; preview and the run header show the effective set.
+
+```ruby
+Saboteur.configure do |c|
+  c.operators = [] # all by default; or ["arithmetic", "range"] for a subset
+  c.exclude_operators = ["condition_negation"]
+end
+```
 
 Inspired by mutineer's --dry-run, --list-operators and --operators tiers (github.com/davidteren/mutineer, MIT, by David Teren).
 
@@ -957,9 +989,11 @@ step; the bundled Action's upload behavior is unchanged.
 
 Score history now refuses non-regular files, symlink paths and report/history
 inode aliases before running the engine or writing reports. Imported records
-have a 64 KiB per-line bound and strict version-one validation, including
-counts, scores and duplicate keys. History is an output, excluded from baseline
+have a 64 KiB per-line bound and strict validation of supported version 1
+and version 2 records, including counts, scores and duplicate keys. History is an output, excluded from baseline
 fingerprints. See [history safety and comparison limits](docs/scores.md).
+
+Operator policy version 2, selected names, excluded names and effective names are in JSON/agent/baseline evidence and fresh score-history v2 rows. Old history v1 rows remain readable but are not compared across policy versions.
 ### Inline suppression comments
 
 `total = a + b # saboteur:disable-line arithmetic reason="rounding checked elsewhere"` suppresses edits starting on that line, restricted to the named operators. Omit names to suppress all operators. Multiple names are space-separated. Only actual Ruby comments count; directive text in strings does not. A missing or blank reason or unknown operator is a usage error naming file:line. Terminal, JSON and HTML list every suppressed candidate with its reason and digest, outside the score. Moving the commented code keeps the suppression. Multi-line edits use their starting line.

data/lib/saboteur/baseline/comparison.rb

@@ -19,6 +19,7 @@ module Saboteur
         @issues = current.fetch("issues").dup
         @categories = {}
         unless baseline.fetch("compatibility") == current.fetch("compatibility")
+          @issues << "baseline inputs or operator policy changed; re-propose with baseline propose"
           @state = "incompatible"
           return
         end

data/lib/saboteur/baseline/evidence.rb

@@ -56,7 +56,7 @@ module Saboteur
         compatibility = document.fetch("compatibility")
         config = compatibility.fetch("config")
         runtime = compatibility.fetch("runtime")
-        fields!(config, Config::DEFAULTS.keys - RunEvidence::OUTPUT_SETTINGS)
+        validate_operator_policy(config)
         fields!(runtime, %w[engine version platform patchlevel saboteur])
         raise ConfigError, "baseline nonfresh config" if config["since"] || config["incremental"]
 
@@ -69,6 +69,16 @@ module Saboteur
         validate_generator(compatibility.fetch("generator"), config, runtime)
       end
 
+      def validate_operator_policy(config)
+        unless config["operator_policy"] && config["operator_policy"]["version"] == MutationSource::OperatorRegistry::POLICY_VERSION
+          raise ConfigError, "baseline operator policy is incompatible; re-propose with baseline propose"
+        end
+
+        fields!(config, Config::DEFAULTS.keys - RunEvidence::OUTPUT_SETTINGS + ["operator_policy"])
+        expected = Config.new(config.except("operator_policy")).operator_policy
+        raise ConfigError, "baseline operator policy mismatch" unless expected == config["operator_policy"]
+      end
+
       def validate_generator(generator, config, runtime)
         fields!(generator, %w[saboteur sources plugins])
         plugins = document.fetch("snapshot").fetch("inventory").select { |entry| entry["kind"] == "source_plugin" }

data/lib/saboteur/baseline/run_evidence.rb

@@ -95,7 +95,7 @@ module Saboteur
                              entry.kind == "source_plugin"
                            end.map(&:to_h) },
           "runtime" => Engine::RunFingerprint.runtime_identity,
-          "config" => @config.to_h.except(*OUTPUT_SETTINGS),
+          "config" => @config.selection_settings.except(*OUTPUT_SETTINGS),
           "scope" => { "include" => @config["include"], "exclude" => @config["exclude"],
                        "subjects" => @config["subjects"] } }
       end

data/lib/saboteur/cli/run_reporting.rb

@@ -66,7 +66,7 @@ module Saboteur
         return unless path
 
         tree = WorkingTree.new(config.root, ignored: config.output_paths).state
-        scope = config.to_h.except("json_report", "html_report", "score_history", "cache_dir")
+        scope = config.selection_settings.except("json_report", "html_report", "score_history", "cache_dir")
         message = Reporter::ScoreHistory.new(path).append(report, head: tree.head, scope: scope)
         @err.puts("saboteur: #{message}")
       end

data/lib/saboteur/cli.rb

@@ -212,10 +212,15 @@ module Saboteur
         subjects: Array(config["subjects"]), tests: Array(engine.guessed_tests || options[:tests]),
         sources: @sources || [],
         config_path: options[:config], digest: options[:id], cache: config["cache"],
-        incremental: config["incremental"], settings: options.slice(*Reporter::Agent::Commands::SETTING_FLAGS.keys)
+        incremental: config["incremental"], settings: agent_settings
       )
     end
 
+    def agent_settings
+      options.slice(*Reporter::Agent::Commands::SETTING_FLAGS.keys)
+             .merge(operators: config["operators"], exclude_operators: config["exclude_operators"])
+    end
+
     def agent_mode
       return "replay" if options[:id]
       return "diff" if config["since"]
@@ -286,17 +291,23 @@ module Saboteur
       raise UsageError, "--dry-run and --list-operators print text, not --agent JSON" if agent?
       raise UsageError, "--id replays one mutant: not with --dry-run or --list-operators" if options[:id]
 
-      return MutationSource::OperatorRegistry.list(@out) || EXIT_OK if options[:list_operators]
+      if options[:list_operators]
+        MutationSource::OperatorRegistry.list(@out, names: config["operators"], excluded: config["exclude_operators"])
+        return EXIT_OK
+      end
 
       Preview.new(config, out: @out, err: @err).call
       EXIT_OK
     end
 
     def define_selection_options(opts)
-      opts.on("--operators NAMES", Array, "Choose operator names or tiers (core, extended, all)") do |v|
+      opts.on("--operators NAMES", Array, "Choose operator names (default: all)") do |v|
         set(:operators, v)
       end
-      opts.on("--list-operators", "List operator names, descriptions and tiers") { set(:list_operators, true) }
+      opts.on("--exclude-operators NAMES", Array, "Exclude operator names from the selected set") do |v|
+        set(:exclude_operators, v)
+      end
+      opts.on("--list-operators", "List operator names and descriptions") { set(:list_operators, true) }
       opts.on("--dry-run", "Preview mutants without boot, tests, forks or report writes") { set(:dry_run, true) }
       opts.on("--id DIGEST", "Replay exactly one current mutant by its full digest") { |v| set(:id, v) }
       opts.on("--since REF", "Only mutate subjects changed since git REF") { |v| options[:since] = v }

data/lib/saboteur/config.rb

@@ -39,8 +39,11 @@ module Saboteur
       "custom_map" => "config/saboteur_custom_map.rb",
       "sources" => ["builtin"],
       "operators" => [],
+      "exclude_operators" => [],
       "hooks" => [],
       "rails" => false,
+      # Hosts the user asserts are disposable test databases (issue #258).
+      "allow_db_hosts" => [],
       "reeval" => "nesting",
       "cache_dir" => ".saboteur",
       "json_report" => ".saboteur/report.json",
@@ -68,7 +71,7 @@ module Saboteur
     THRESHOLD_RANGE = (0.0..100.0)
 
     LIST_KEYS = %w[require include exclude arid hazard sources hooks rspec_args subjects tests
-                   fingerprint_extra sandbox_writable operators whole_file].freeze
+                   fingerprint_extra sandbox_writable operators exclude_operators whole_file allow_db_hosts].freeze
 
     attr_reader :root
 
@@ -236,8 +239,25 @@ module Saboteur
       validate_operator_config!
     end
 
+    public
+
+    def operator_policy
+      MutationSource::OperatorRegistry.policy(self["operators"], self["exclude_operators"])
+    end
+
+    # Versioned policy travels with every identity, not with mutation digests.
+    def selection_settings
+      to_h.merge("operator_policy" => operator_policy)
+    end
+
+    private
+
     def validate_operator_config!
-      MutationSource::OperatorRegistry.resolve(self["operators"])
+      effective = MutationSource::OperatorRegistry.select(self["operators"], self["exclude_operators"])
+      if effective.empty?
+        raise ConfigError,
+              "operator selection is empty: enable at least one operator or clear exclusions"
+      end
 
       self["arid"].each { |pattern| Regexp.new(pattern) }
     rescue RegexpError => e

data/lib/saboteur/doctor.rb

@@ -25,6 +25,7 @@ module Saboteur
       integration = boot_target(hooks)
       @out.puts "Integration: #{@config['integration']} (loaded)"
       @out.puts "Rails: #{@config['rails'] ? 'enabled' : 'disabled'}"
+      check_database_hosts
       @out.puts "SimpleCov: #{defined?(::SimpleCov) ? 'present; start suppressed for this process' : 'not loaded'}"
       check_coverage
       check_suite(integration, hooks)
@@ -105,11 +106,33 @@ module Saboteur
       @out.puts "Custom map: #{map.entries.size} entries (loaded)"
     end
 
+    # Prints the test database hosts the booted app reports, so a non-local
+    # refusal names the host here instead of only at target boot (issue #258).
+    def check_database_hosts
+      return unless @config["rails"]
+      return @out.puts("Databases: ActiveRecord did not load; host check skipped") unless defined?(::ActiveRecord::Base)
+
+      configs = ::ActiveRecord::Base.configurations.configs_for(env_name: "test")
+      configs.each do |db|
+        host = db.configuration_hash[:host]
+        @out.puts "Database: #{db.name} (host #{host.to_s.empty? ? 'local socket' : host})"
+      end
+      remote = Frameworks::Rails.remote_databases(configs, @config["allow_db_hosts"])
+      return if remote.empty?
+
+      raise ConfigError, "non-local test databases: #{remote.join(', ')}; if they are disposable test databases, " \
+                         "allow them with c.allow_db_hosts in #{Config::FILE}"
+    end
+
     def check_boot_files
       %w[require hooks].each do |key|
         @config[key].each do |file|
           path = File.expand_path(file, @config.root)
-          raise ConfigError, "#{key} file missing: #{file}; fix config/saboteur.rb" unless File.file?(path)
+          # Resolve the way Kernel#require does: the path as given, or with
+          # .rb appended (the Rails quickstart sets ./config/environment, issue #257).
+          unless File.file?(path) || File.file?("#{path}.rb")
+            raise ConfigError, "#{key} file missing: #{file}; fix config/saboteur.rb"
+          end
 
           @out.puts "#{key}: #{file} (found)"
         end

data/lib/saboteur/engine/candidates.rb

@@ -13,7 +13,10 @@ module Saboteur
       def self.build_sources(config)
         root = File.realpath(config.root)
         config["sources"].map do |entry|
-          next MutationSource::Builtin.new(arid: config["arid"], operators: config["operators"]) if entry == "builtin"
+          if entry == "builtin"
+            next MutationSource::Builtin.new(arid: config["arid"], operators: config["operators"],
+                                             exclude_operators: config["exclude_operators"])
+          end
 
           file, const = entry.split(":", 2)
           raise ConfigError, "mutation source #{entry.inspect} must be builtin or path.rb:ClassName" unless const

data/lib/saboteur/engine/run_fingerprint.rb

@@ -127,7 +127,7 @@ module Saboteur
         issues = output_overlap_issues
         entries = inventory(issues).sort_by(&:path).freeze
         issues = issues.uniq.sort
-        settings_digest = hash_value(@config.to_h.except(*LOCATION_SETTINGS))
+        settings_digest = hash_value(@config.selection_settings.except(*LOCATION_SETTINGS))
         runtime_digest = hash_value(@runtime_identity)
         digest = hash_value(format: FORMAT_VERSION, files: entries.map(&:to_h),
                             settings: settings_digest, runtime: runtime_digest)

data/lib/saboteur/engine/test_guess.rb

@@ -6,8 +6,9 @@ module Saboteur
     # --guess-tests: the specs that sit next to the changed source files by
     # naming convention (lib/a/b.rb -> spec/a/b_spec.rb). A guess, not a
     # coverage fact: a spec that only reaches the file through another one
-    # is not found. The run scopes to the guesses only when every changed
-    # file has one.
+    # is not found. Packwerk packs (a directory with a package.yml) map to the
+    # spec directory inside the same pack, and controllers also map to request
+    # specs. The run scopes to the guesses only when every changed file has one.
     class TestGuess
       Result = Data.define(:specs, :unmatched, :changed)
 
@@ -40,12 +41,48 @@ module Saboteur
       end
 
       def guess_for(file)
-        stem = file.delete_suffix(".rb")
+        candidates_for(file).find { |path| File.file?(File.join(@root, path)) }
+      end
+
+      # Candidate specs for a source file, most specific first: the nearest
+      # package.yml pack's own spec directory, then the app-wide one.
+      def candidates_for(file)
+        pack = pack_of(file)
+        # pack is nil for files outside packs: "#{nil}/" is "/", which
+        # never prefixes a relative path, so delete_prefix is a no-op there.
+        base = file.delete_prefix("#{pack}/")
+        spec_root = pack ? "#{pack}/spec" : "spec"
+        stem = base.delete_suffix(".rb")
         rest = stem.split("/", 2)
-        candidates = ["spec/#{stem}_spec.rb"]
-        candidates.unshift("spec/#{rest.last}_spec.rb", "spec/lib/#{rest.last}_spec.rb") if
-          rest.size == 2 && SOURCE_ROOTS.include?(rest.first)
-        candidates.find { |path| File.file?(File.join(@root, path)) }
+        rooted = rest.size == 2 && SOURCE_ROOTS.include?(rest.first)
+        names = rooted ? [rest.last, "lib/#{rest.last}", stem] : [stem]
+        names = names.flat_map { |name| [name, *request_names(name)] }.uniq
+        names.map { |name| "#{spec_root}/#{name}_spec.rb" }
+      end
+
+      # Rails tests controllers as request specs: spec/requests/users_spec.rb
+      # or spec/requests/users_controller_spec.rb for controllers/users_controller.rb.
+      def request_names(name)
+        return [] unless name.start_with?("controllers/")
+
+        path = name.delete_prefix("controllers/")
+        ["requests/#{path}", "requests/#{path.delete_suffix('_controller')}"].uniq
+      end
+
+      # The nearest ancestor directory holding a package.yml (a packwerk
+      # pack), relative to the root. The root itself is not a pack here:
+      # its specs follow the plain mapping.
+      def pack_of(file)
+        dir = File.dirname(file)
+        until dir == "."
+          return dir if pack_dirs.include?(dir)
+
+          dir = File.dirname(dir)
+        end
+      end
+
+      def pack_dirs
+        @pack_dirs ||= Dir.glob("**/package.yml", base: @root).to_set { |path| File.dirname(path) }
       end
     end
   end

data/lib/saboteur/engine.rb

@@ -13,7 +13,8 @@ module Saboteur
   # engine/; this class only wires them together.
   class Engine
     # Everything besides sources and tests that can change a verdict.
-    VERDICT_INPUTS = %w[integration require rspec_args rails reeval sources operators arid timeout_factor timeout_min
+    VERDICT_INPUTS = %w[integration require rspec_args rails reeval sources operators exclude_operators arid
+                        timeout_factor timeout_min
                         max_memory_mb max_processes seed tests whole_file].freeze
 
     attr_reader :config, :hooks
@@ -41,6 +42,7 @@ module Saboteur
       refuse_fail_fast_evidence
       started = monotonic
       guess_tests
+      announce_operators
       @run_evidence = Baseline::RunEvidence.new(config: config, extra_files: @evidence_files) if @capture_evidence
       ignore_list = @replay ? IgnoreList.new([]) : IgnoreList.load(config.path("ignore_file"))
       warn_custom_map
@@ -110,6 +112,10 @@ module Saboteur
     end
 
     # The run's immutable report, built once the last result is in.
+    def announce_operators
+      @diagnostics.inform("Operators: #{config.operator_policy['effective'].join(', ')}")
+    end
+
     def build_report(results, subjects, scope, started)
       Report.new(results: results, subjects: subjects, wall_time: monotonic - started, root: @root,
                  invalid_mutations: @diagnostics.invalid_mutations, warnings: @diagnostics.warnings,
@@ -117,7 +123,8 @@ module Saboteur
                  diff_scope: scope, generation_events: @diagnostics.generation_events,
                  omissions: @diagnostics.omissions, run_evidence: complete_evidence(results, subjects),
                  hazard_suppressions: @diagnostics.hazard_suppressions, early_stop: @early_stop,
-                 matrix: config["matrix"], inline_suppressions: @diagnostics.inline_suppressions)
+                 matrix: config["matrix"], inline_suppressions: @diagnostics.inline_suppressions,
+                 operator_policy: config.operator_policy)
     end
 
     def complete_evidence(results, subjects)
@@ -249,7 +256,8 @@ module Saboteur
       return nil if @replay
       return nil unless config["incremental"]
 
-      inputs = JSON.generate(VERDICT_INPUTS.to_h { |key| [key, config[key]] })
+      inputs = JSON.generate(VERDICT_INPUTS.to_h { |key| [key, config[key]] }
+                                            .merge("operator_policy" => config.operator_policy))
       ResultCache.new(path: File.join(config.path("cache_dir"), "results.json"), root: @root, inputs: inputs,
                       suite_digest: SuiteFiles.new(config).digest)
     end

data/lib/saboteur/frameworks/database_hosts.rb

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Frameworks
+    # Which database hosts count as local for the Rails integration's refusal
+    # to mutate a remote test database (issue #258).
+    module DatabaseHosts
+      # 0.0.0.0: a listen address, but in a URL it connects to this machine (issue #258).
+      LOCAL_HOSTS = ["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"].freeze
+
+      module_function
+
+      def local?(host)
+        host = host.to_s
+        host.empty? || host.start_with?("/") || LOCAL_HOSTS.include?(host.downcase)
+      end
+
+      # "name (host host)" per config whose host is not local and not in
+      # extra_allowed. Shared by the boot refusal and doctor.
+      def remote(configs, extra_allowed = [])
+        allowed = extra_allowed.map(&:downcase)
+        configs.filter_map do |db|
+          host = db.configuration_hash[:host]
+          "#{db.name} (host #{host})" unless local?(host) || allowed.include?(host.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/saboteur/frameworks/rails.rb

@@ -7,6 +7,8 @@ require "pathname"
 require "English"
 require "tmpdir"
 
+require_relative "database_hosts"
+
 module Saboteur
   module Frameworks
     # Opt-in Rails support (`c.rails = true` in config/saboteur.rb).
@@ -16,8 +18,6 @@ module Saboteur
     # forking, and drops database connections in the parent so each child opens
     # its own. Prints host names only, never credentials.
     class Rails
-      LOCAL_HOSTS = ["localhost", "127.0.0.1", "::1", "[::1]"].freeze
-
       # How many blocking session names the template-copy error lists.
       MAX_BLOCKER_NAMES = 5
 
@@ -170,9 +170,9 @@ module Saboteur
         db.adapter.to_s.match?(/sqlite/) && db.database.to_s == ":memory:"
       end
 
-      def self.local_host?(host)
-        host.nil? || host.to_s.empty? || host.to_s.start_with?("/") || LOCAL_HOSTS.include?(host.to_s.downcase)
-      end
+      def self.local_host?(host) = DatabaseHosts.local?(host)
+
+      def self.remote_databases(configs, extra_allowed = []) = DatabaseHosts.remote(configs, extra_allowed)
 
       private
 
@@ -197,13 +197,11 @@ module Saboteur
       def check_databases
         return unless defined?(::ActiveRecord::Base)
 
-        remote = ::ActiveRecord::Base.configurations.configs_for(env_name: "test").filter_map do |db|
-          host = db.configuration_hash[:host]
-          "#{db.name} (host #{host})" unless self.class.local_host?(host)
-        end
+        remote = self.class.remote_databases(test_configs, @config["allow_db_hosts"])
         return if remote.empty?
 
-        raise Error, "rails integration refuses to run against non-local databases: #{remote.join(', ')}"
+        raise Error, "rails integration refuses to run against non-local databases: #{remote.join(', ')}; " \
+                     "if they are disposable test databases, allow them with c.allow_db_hosts in #{Config::FILE}"
       end
 
       def test_configs

data/lib/saboteur/help.rb

@@ -42,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. Inline comment syntax: " \
+                     "PERCENT, exit 1 when it is below. All operators run unless you select a smaller set; " \
+                     "exclusions always remove operators from that set. Inline comment syntax: " \
                      '# saboteur:disable-line [operator ...] reason="...". A reason is required.',
         takes_options: true,
         exit_codes: EXIT_CODE_MEANINGS,

data/lib/saboteur/mutation_source/builtin.rb

@@ -53,9 +53,9 @@ module Saboteur
       CATCH_ALL = %w[StandardError ::StandardError Exception ::Exception].freeze
       SCOPE_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
 
-      def initialize(arid: DEFAULT_ARID, operators: [])
+      def initialize(arid: DEFAULT_ARID, operators: [], exclude_operators: [])
         super()
-        @operators = OperatorRegistry.resolve(operators)
+        @operators = OperatorRegistry.select(operators, exclude_operators)
         @arid = arid.map { |pattern| pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern) }
         @filter_replacement = FilterReplacement.new(arid: arid)
         @literal_replacement = LiteralReplacement.new(arid: arid)

data/lib/saboteur/mutation_source/operator_examples.rb

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module MutationSource
+    module OperatorExamples
+      EXAMPLES = {
+        "body_nil" => "def value = 1 -> def value = nil",
+        "body_true" => "def ok? = false -> def ok? = true",
+        "body_false" => "def ok? = true -> def ok? = false",
+        "body_raise" => "def value = 1 -> def value; raise; end",
+        "comparison" => "a < b -> a <= b",
+        "arithmetic" => "a + b -> a - b",
+        "boolean_logic" => "a && b -> a",
+        "condition_true" => "if x -> if true",
+        "condition_false" => "if x -> if false",
+        "negation_removal" => "!x -> x",
+        "literal_number" => "1 -> 0",
+        "or_assign" => "x ||= 1 -> x = 1",
+        "safe_navigation" => "x&.name -> x.name",
+        "statement_removal" => "check; value -> nil; value",
+        "filter_replacement" => "xs.select { |x| x } -> xs.reject { |x| x }",
+        "literal_string" => "\"hello\" -> \"\"",
+        "literal_boolean" => "true -> false",
+        "argument_removal" => "send(a, b) -> send(a)",
+        "pair_removal" => "{a: 1, b: 2} -> {b: 2}",
+        "endpoint_replacement" => "xs.first -> xs.last",
+        "chain_removal" => "x.first.to_s -> x.to_s",
+        "range" => "1..3 -> 1...3",
+        "operator_assignment" => "x += 1 -> x -= 1",
+        "condition_negation" => "x ? a : b -> !(x) ? a : b"
+      }.freeze
+    end
+  end
+end

data/lib/saboteur/mutation_source/operator_registry.rb

@@ -1,6 +1,9 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require "did_you_mean"
+require_relative "operator_examples"
+
 module Saboteur
   module MutationSource
     # Public names used by selection, help and inline suppression validation.
@@ -31,24 +34,46 @@ module Saboteur
         "endpoint_replacement" => "Swap explicit no-argument first and last",
         "chain_removal" => "Remove one call from a method chain"
       }.freeze
-      EXTENDED = %w[range operator_assignment condition_negation].freeze
-      TIERS = { "core" => (DESCRIPTIONS.keys - EXTENDED).freeze, "extended" => EXTENDED,
-                "all" => DESCRIPTIONS.keys.freeze }.freeze
+      POLICY_VERSION = 2
+      TIERS = { "all" => DESCRIPTIONS.keys.freeze }.freeze
 
-      def self.list(out)
+      def self.list(out, names: [], excluded: [])
+        active = select(names, excluded)
         DESCRIPTIONS.each do |name, description|
-          out.puts("#{name}  #{EXTENDED.include?(name) ? 'extended' : 'core'}  #{description}")
+          out.puts("#{name}  #{active.include?(name) ? 'on' : 'off'}  #{description}  #{OperatorExamples::EXAMPLES.fetch(name)}")
         end
         nil
       end
 
+      def self.policy(names, excluded)
+        { "version" => POLICY_VERSION, "selected" => names, "excluded" => excluded,
+          "effective" => select(names, excluded) }
+      end
+
+      # Exclusion wins over explicit selection; empty exclusions remove nothing.
+      def self.select(names, excluded)
+        selected = resolve(names)
+        excluded.empty? ? selected : selected - resolve(excluded)
+      end
+
+      def self.suggestion(name)
+        matches = DidYouMean::SpellChecker.new(dictionary: DESCRIPTIONS.keys).correct(name)
+        matches.empty? ? "" : "Did you mean #{matches.first}?"
+      end
+
       def self.resolve(names)
-        return TIERS.fetch("core") if names.empty?
+        return TIERS.fetch("all") if names.empty?
 
+        legacy = names & %w[core extended]
+        unless legacy.empty?
+          raise ConfigError, "operator tiers #{legacy.join(', ')} were removed: use concrete names or all; " \
+                             "for the old core set exclude range,operator_assignment,condition_negation"
+        end
         unknown = names - DESCRIPTIONS.keys - TIERS.keys
         unless unknown.empty?
           raise ConfigError, "unknown operators: #{unknown.join(', ')}. Valid names: " \
-                             "#{(DESCRIPTIONS.keys + TIERS.keys).join(', ')}"
+                             "#{(DESCRIPTIONS.keys + TIERS.keys).join(', ')}. " \
+                             "#{suggestion(unknown.first)} See --list-operators."
         end
         names.flat_map { |name| TIERS.fetch(name) { [name] } }.uniq
       end

data/lib/saboteur/preview.rb

@@ -13,6 +13,7 @@ module Saboteur
     end
 
     def call
+      announce_operators
       selection = Engine::SubjectSelection.new(@config, @diagnostics)
       subjects = selection.select(@config.included_files)
       scope = selection.changed_lines && Engine::DiffScope.new(selection.changed_lines)
@@ -24,12 +25,20 @@ module Saboteur
       @out.puts("Total: #{lists.sum(&:size)} mutants; #{@diagnostics.omissions.sum(&:count)} " \
                 "dropped by max_mutants_per_method#{incomplete_note(incomplete)}")
       incomplete.zero? ? estimate(subjects, lists) : @out.puts("no estimate: source discovery was incomplete")
-      @diagnostics.warnings.each { |warning| @out.puts("warning: #{warning}") }
+      print_warnings
       nil
     end
 
     private
 
+    def print_warnings
+      @diagnostics.warnings.each { |warning| @out.puts("warning: #{warning}") }
+    end
+
+    def announce_operators
+      @out.puts("Operators: #{@config.operator_policy['effective'].join(', ')}")
+    end
+
     # Candidate filtering precedes diff restriction and the per-method cap.
     # Name that scope rather than implying these rows were executed or scored.
     def inline_suppressions

data/lib/saboteur/reporter/agent_commands.rb

@@ -15,7 +15,8 @@ module Saboteur
 
         # Options typed on the command line that change how a run behaves.
         SETTING_FLAGS = { reeval: "--reeval", integration: "--integration", jobs: "--jobs",
-                          timeout_factor: "--timeout-factor", json_report: "--json", html_report: "--html" }.freeze
+                          timeout_factor: "--timeout-factor", json_report: "--json", html_report: "--html",
+                          operators: "--operators", exclude_operators: "--exclude-operators" }.freeze
 
         class << self
           # Run the same selection again: ref, subjects, sources, tests, config,
@@ -46,15 +47,22 @@ module Saboteur
             tests.empty? ? [] : ["--no-guess-tests", *tests.flat_map { |test| ["--test", test] }]
           end
 
+          def setting_words(provenance)
+            SETTING_FLAGS.flat_map do |key, flag|
+              next [] unless provenance.settings.key?(key)
+
+              value = provenance.settings[key]
+              [flag, value.is_a?(Array) ? value.join(",") : value.to_s]
+            end
+          end
+
           def selection(provenance, replay: false)
             words = []
             words.push("--config", provenance.config_path) if provenance.config_path
             words.push("--since", provenance.ref) if provenance.ref
             provenance.subjects.each { |subject| words.push("--subject", subject) }
             words.push(*test_words(provenance.tests))
-            SETTING_FLAGS.each do |key, flag|
-              words.push(flag, provenance.settings[key].to_s) if provenance.settings.key?(key)
-            end
+            words.concat(setting_words(provenance))
             words << "--no-cache" if provenance.cache == false
             words << "--incremental" if provenance.incremental
             words.push("--id", provenance.digest) if provenance.digest && !replay

data/lib/saboteur/reporter/agent_summary.rb

@@ -22,7 +22,7 @@ module Saboteur
             verdict = verdict_of(report, status)
             {
               version: VERSION, status: status, verdict: verdict, exitCode: exit_code_for(verdict),
-              provenance: provenance_hash(provenance),
+              provenance: provenance_hash(provenance).merge(operatorPolicy: report.operator_policy),
               counts: counts(report), score: score(report),
               scoreDefinition: "(killed + timeout) / (killed + survived + timeout); null when nothing was tested",
               incomplete: incomplete, timeoutCountedAsDetected: report.counts[:timeout],

data/lib/saboteur/reporter/history_policy.rb

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Reporter
+    # v1 stays readable, but v2 records require versioned operator evidence.
+    module HistoryPolicy
+      def validate_header(record, fields)
+        version = record.is_a?(Hash) && record["version"]
+        raise Error, "score history contains an invalid version" unless version.is_a?(Integer) && [1,
+                                                                                                   2].include?(version)
+
+        fields(record, version == 2 ? fields + ["operatorPolicy"] : fields)
+        validate_policy(record["operatorPolicy"]) if version == 2
+      end
+
+      def validate_policy(value)
+        raise Error, "score history contains invalid operator policy" unless value.is_a?(Hash)
+
+        fields(value, %w[version selected excluded effective])
+        raise Error, "score history contains invalid operator policy" if value["effective"].empty?
+
+        lists = value.values_at("selected", "excluded", "effective")
+        unless lists.all? { |list| list.is_a?(Array) && list.all?(String) }
+          raise Error, "score history contains invalid operator policy"
+        end
+
+        expected = MutationSource::OperatorRegistry.policy(value["selected"], value["excluded"])
+        raise Error, "score history contains invalid operator policy" unless value == expected
+      rescue ConfigError, NoMethodError, TypeError
+        raise Error, "score history contains invalid operator policy"
+      end
+    end
+  end
+end

data/lib/saboteur/reporter/history_record.rb

@@ -3,6 +3,7 @@
 
 require "json"
 require "time"
+require_relative "history_policy"
 
 module Saboteur
   module Reporter
@@ -21,6 +22,8 @@ module Saboteur
         end
       end
 
+      extend HistoryPolicy
+
       module_function
 
       def parse(line)
@@ -32,11 +35,7 @@ module Saboteur
       end
 
       def validate(record)
-        fields(record, FIELDS)
-        unless record.fetch("version").is_a?(Integer) && record.fetch("version") == 1
-          raise Error,
-                "score history contains an invalid version"
-        end
+        validate_header(record, FIELDS)
 
         date(record.fetch("date"))
         commit = record.fetch("commit")

data/lib/saboteur/reporter/score_history.rb

@@ -13,6 +13,7 @@ module Saboteur
     # Opt-in append-only score observations, not a baseline or a CI gate.
     class ScoreHistory
       DIFFERENT_RUN = "score history: change unavailable (different selection/inventory or incomplete run)"
+      DIFFERENT_POLICY = "score history: change unavailable (different record version or operator policy)"
       MISSING_SCORE = "score history: change unavailable (no tested mutants)"
       MAX_RECORD_BYTES = 64 * 1024
       OPEN_FLAGS = File::RDWR | File::CREAT | File::NONBLOCK | File::NOFOLLOW
@@ -58,13 +59,13 @@ module Saboteur
       private
 
       def build(report, head, scope)
-        { "version" => 1, "date" => Time.now.utc.iso8601, "commit" => head,
+        { "version" => 2, "date" => Time.now.utc.iso8601, "commit" => head,
           "selection" => Digest::SHA256.hexdigest(JSON.generate(scope.sort_by { |key, _| key.to_s }.to_h)),
           "inventory" => Digest::SHA256.hexdigest(JSON.generate(report.results.map(&:digest).sort)),
           "score" => overall_score(report), "coveredScore" => report.score,
           "counts" => report.counts.transform_keys(&:to_s),
           "breakdown" => report.score_breakdown.to_h.transform_keys(&:to_s),
-          "incomplete" => incompleteness(report) }
+          "incomplete" => incompleteness(report), "operatorPolicy" => report.operator_policy }
       end
 
       def overall_score(report)
@@ -107,11 +108,22 @@ module Saboteur
         previous
       end
 
+      # Only one record version and one non-null operator policy compare:
+      # scores never mix across v1/v2 or across policy configurations.
+      # A non-null previous policy forces a non-null equal current one, so
+      # only the previous record needs the null guard.
+      def comparable_policy?(previous, current)
+        previous["version"] == current["version"] &&
+          !previous["operatorPolicy"].nil? &&
+          previous["operatorPolicy"] == current["operatorPolicy"]
+      end
+
       def change(previous, current)
         return "score history: first record" unless previous
         return DIFFERENT_RUN unless
           previous["selection"] == current["selection"] && previous["inventory"] == current["inventory"] &&
           previous["incomplete"].empty? && current["incomplete"].empty?
+        return DIFFERENT_POLICY unless comparable_policy?(previous, current)
         return MISSING_SCORE if
           previous["coveredScore"].nil? || current["coveredScore"].nil?
 

data/lib/saboteur/reporter/stryker.rb

@@ -40,13 +40,15 @@ module Saboteur
           warnings: report.warnings,
           framework: { name: "saboteur", version: VERSION },
           saboteur: { findings: Findings.build(report), scores: scores(report),
-                      inlineSuppressions: report.inline_suppressions.map do |entry|
-                        entry.merge(file: relative(entry[:file], report.root))
-                      end }
-                     .merge(exit_cause ? { exitCause: exit_cause } : {})
+                      inlineSuppressions: inline_audit(report) }
+                     .merge(operatorPolicy: report.operator_policy).merge(exit_cause ? { exitCause: exit_cause } : {})
         }.merge(report.seed ? { config: { seed: report.seed } } : {})
       end
 
+      def self.inline_audit(report)
+        report.inline_suppressions.map { |entry| entry.merge(file: relative(entry[:file], report.root)) }
+      end
+
       # Score with its assertion and crash shares, for all mutants and without
       # the whole-body ones (body_nil, body_true, body_false, body_raise).
       def self.scores(report)

data/lib/saboteur/reporter/terminal.rb

@@ -34,11 +34,20 @@ module Saboteur
         warnings(report)
         early_stop(report)
         test_matrix(report)
+        operator_policy(report)
         summary(report)
       end
 
       private
 
+      def operator_policy(report)
+        policy = report.operator_policy
+        return unless policy && policy["excluded"].any?
+
+        @out.puts("Excluded operators: #{policy['excluded'].join(', ')} " \
+                  "(policy #{policy['version']}; #{policy['effective'].size} enabled)")
+      end
+
       def test_matrix(report)
         return unless report.matrix?
 

data/lib/saboteur/result.rb

@@ -112,13 +112,15 @@ module Saboteur
     MAX_ERROR_FRACTION = 0.5
 
     attr_reader :results, :subjects, :wall_time, :invalid_mutations, :warnings, :root, :seed, :skipped_subjects,
-                :generation_events, :omissions, :run_evidence, :hazard_suppressions, :early_stop, :inline_suppressions
+                :generation_events, :omissions, :run_evidence, :hazard_suppressions, :early_stop, :inline_suppressions,
+                :operator_policy
 
     # REVIEW: diff mode; the terminal then shows one survivor per line.
     # seed: the random seed every test run started from (nil when unknown).
     def initialize(results:, subjects:, wall_time:, root:, invalid_mutations: 0, warnings: [], review: false,
                    seed: nil, skipped_subjects: {}, diff_scope: nil, generation_events: [], omissions: [],
-                   run_evidence: nil, hazard_suppressions: 0, early_stop: nil, matrix: false, inline_suppressions: [])
+                   run_evidence: nil, hazard_suppressions: 0, early_stop: nil, matrix: false, inline_suppressions: [],
+                   operator_policy: nil)
       @results = results
       @subjects = subjects
       @wall_time = wall_time
@@ -136,6 +138,7 @@ module Saboteur
       @early_stop = early_stop
       @matrix = matrix
       @inline_suppressions = inline_suppressions.dup.freeze
+      @operator_policy = operator_policy
     end
 
     # A --matrix run: every covering test ran per mutant.

data/lib/saboteur/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Saboteur
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: saboteur
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Vamsi Pavan Mahesh Gunturu
@@ -110,6 +110,7 @@ files:
 - lib/saboteur/execution/supervisor.rb
 - lib/saboteur/execution/worker_pool.rb
 - lib/saboteur/execution/wrapper.rb
+- lib/saboteur/frameworks/database_hosts.rb
 - lib/saboteur/frameworks/rails.rb
 - lib/saboteur/gates.rb
 - lib/saboteur/help.rb
@@ -132,6 +133,7 @@ files:
 - lib/saboteur/mutation_source/literal_replacement.rb
 - lib/saboteur/mutation_source/mutation.rb
 - lib/saboteur/mutation_source/operator_assignment.rb
+- lib/saboteur/mutation_source/operator_examples.rb
 - lib/saboteur/mutation_source/operator_registry.rb
 - lib/saboteur/mutation_source/pair_removal.rb
 - lib/saboteur/mutation_source/range_replacement.rb
@@ -145,6 +147,7 @@ files:
 - lib/saboteur/reporter/diff.rb
 - lib/saboteur/reporter/findings.rb
 - lib/saboteur/reporter/history_paths.rb
+- lib/saboteur/reporter/history_policy.rb
 - lib/saboteur/reporter/history_record.rb
 - lib/saboteur/reporter/html.rb
 - lib/saboteur/reporter/mutation_text.rb