active_mutator 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45e58d5b8880a6716b7a78ee4011f0e5529600b3daa222ad39854723d08bd9d3
-  data.tar.gz: d9c9067771e0596e3241d8a0bb408c3c9f041e98eac33f08066b1118feedb5b8
+  metadata.gz: 60c123ba92745825d5041728a14144e2cad95ba814d54fcb72bba40e1d5c0089
+  data.tar.gz: b7f96c322c455aa01d4ef19e04aa017f61fecb82347b1da7e315cfdc4316708e
 SHA512:
-  metadata.gz: 2e6881dce81b23302b40220a9b593b290b22b08eb5f6c4426da96e2f5557e369cd635525f32aa357078c6ae10f289c05d216b025992ce23ff607841b42b71b1b
-  data.tar.gz: 25fbb644044f506fcc4663ed26be6898187a4205a91778fdfc049240ecf7c1bb54a52f81b38e2ab9f59f75c00f0bbcd5d93b8ad6bc0d7c7a149d90cdc4f69cf4
+  metadata.gz: 134766964d548d79002d0364046d6a46cb9a3b3d14b334c7d7ee67b3581865c31f10184bd7666d59f5732122dbc74f8c8ffdd7ee14664cd610c38ba64675fc31
+  data.tar.gz: 22bd7813d2a1d061a045a3bc3c7cc2d21c31b3d34f6c8b26e0f2433921b131c124f0f652e3367657bfcc26e987dd7416763c33e05d3e074cfa688703047ec8e2

data/README.md

@@ -131,10 +131,15 @@ discarded before scheduling and reported as a count only. Exit code is `1`
 if unaccepted survivors or errors exist (or, with `--fail-at`, if the score
 is below the threshold), `0` otherwise, including when there are only
 `uncovered` or `accepted` results. The JSON report's `exit_reason` field
-(`unaccepted_survivors`, `worker_errors`, `clean`) is independent of the
-`--fail-at` gate. A `--since`
-or `--subject` run that plans zero mutants prints no score; it warns with the
-cause and exits `1` unless `--allow-empty` is given.
+(`unaccepted_survivors`, `worker_errors`, `clean`, `empty_plan`) is
+independent of the `--fail-at` gate. A `--since` or `--subject` run that
+plans zero mutants skips the baseline, prints the usual count block with
+every status at `0` and no `Mutation score:` line (JSON: `score` is `null`,
+`exit_reason` is `empty_plan`), then warns with the cause and exits `1`
+unless `--allow-empty` is given. The count block is printed on every run,
+whatever the exit code, so log-scraping never has to handle a missing block.
+`--allow-empty` forgives the empty plan only when the `--since` diff touched
+no candidate source file; see [Empty plans in CI](#empty-plans-in-ci).
 
 When survivors exist, the summary also prints a per-operator table showing
 how often each operator's mutants survive, to help spot likely-equivalent
@@ -245,6 +250,29 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
   residual blind spot — constant-reference detection handles the common
   newly-covering-example case since 0.2)
 
+### Empty plans in CI
+
+A `--since` PR run that plans zero mutants skips the baseline, prints the
+zero-count block, and exits `1`. Pass `--allow-empty` to let it decide for
+itself whether that emptiness is fine:
+
+- **Exit 0** when the diff contains no candidate file. A candidate is a
+  changed or untracked `.rb` file inside the scanned paths (positional args
+  or the default `app`/`lib`), not under a spec path, and not matching an
+  `--exclude` pattern. Docs-only, spec-only, and excluded-path PRs pass.
+- **Exit 0** with `--no-class-level` when every changed line in the
+  candidate files falls inside class-body code that flag dropped. The
+  warning names `--no-class-level` as the reason.
+- **Exit 1** otherwise. A candidate source file changed but produced no
+  mutants, and the warning lists the file(s). A comment-only edit in `lib/`
+  counts as a real change here.
+- With `--subject` and no `--since` there is no diff to judge, so
+  `--allow-empty` exits `0` unconditionally.
+
+`--changed` follows the same rule, and an untracked candidate `.rb` file
+counts as a candidate. This replaces the repo-side log-scraping script some
+projects used to tell a docs-only PR from a broken `--since` range.
+
 ## Flags
 
 | Flag | Default | Meaning |
@@ -256,7 +284,7 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
 | `--exclude PAT` | none | skip files matching glob during subject discovery (repeatable, gitignore-like) |
 | `--max-mutants N` | none | deterministic sample of the first N mutants (quick smoke run on huge scopes; accepted/uncovered mutants count against N) |
 | `--debug-plan` | off | print planned mutants as JSON and exit without running |
-| `--allow-empty` | off | exit 0 when `--since`/`--subject` plan no mutants (default: warn and exit 1) |
+| `--allow-empty` | off | forgive an empty `--since`/`--subject` plan, but only when the `--since` diff touched no candidate source file (default: warn and exit 1) |
 | `--format terminal\|json\|stryker-json\|github` | terminal | report format |
 | `--accept-survivors` | off | record survivors to the acceptance ledger |
 | `--force-baseline` | off | ignore cached coverage map |

data/lib/active_mutator/cli.rb

@@ -66,7 +66,9 @@ module ActiveMutator
         o.on("--exclude PAT", "Skip files matching glob, relative to root (repeatable)") { |v| options[:exclude] << v }
         o.on("--max-mutants N", Integer, "Deterministically sample the first N mutants") { |v| options[:max_mutants] = v }
         o.on("--debug-plan", "Print the planned mutant list as JSON and exit") { options[:debug_plan] = true }
-        o.on("--allow-empty", "Exit 0 when --since/--subject plan no mutants (default: exit 1)") { options[:allow_empty] = true }
+        o.on("--allow-empty",
+             "Exit 0 when --since/--subject plan no mutants and the --since diff touched no mutable " \
+             "source file (default: exit 1)") { options[:allow_empty] = true }
         o.on("--fail-at SCORE", Float, "Exit 0 if mutation score >= SCORE even with survivors (default: any survivor fails)") do |v|
           raise OptionParser::InvalidArgument, "--fail-at must be within 0..100" unless (0..100).cover?(v)
           options[:fail_at] = v

data/lib/active_mutator/reporter/github.rb

@@ -12,8 +12,8 @@ module ActiveMutator
 
       def on_result(result) = @terminal.on_result(result)
 
-      def summary(results, invalid_count:)
-        @terminal.summary(results, invalid_count: invalid_count)
+      def summary(results, invalid_count:, empty_plan: false)
+        @terminal.summary(results, invalid_count: invalid_count, empty_plan: empty_plan)
         results.select { |r| r.status == :survived }.each { |r| annotate(r) }
       end
 

data/lib/active_mutator/reporter/json.rb

@@ -9,23 +9,26 @@ module ActiveMutator
 
       def on_result(result); end
 
-      def summary(results, invalid_count:)
-        counts = results.group_by(&:status).transform_values(&:size)
+      # An empty plan has no score (null) and its own exit_reason, so a CI
+      # consumer can tell "nothing to mutate" from "everything was killed" (#45).
+      def summary(results, invalid_count:, empty_plan: false)
+        counts = Terminal.counts(results)
         @out.puts JSON.pretty_generate(
-          "score" => Terminal.score(counts),
+          "score" => empty_plan ? nil : Terminal.score(counts),
           "counts" => counts.transform_keys(&:to_s),
           "invalid" => invalid_count,
           "operators" => OperatorStats.call(results),
           "results" => results.map { |r| serialize(r) },
-          "exit_reason" => exit_reason(counts)
+          "exit_reason" => exit_reason(counts, empty_plan)
         )
       end
 
       private
 
-      def exit_reason(counts)
-        return "unaccepted_survivors" if counts.fetch(:survived, 0).positive?
-        return "worker_errors" if counts.fetch(:error, 0).positive?
+      def exit_reason(counts, empty_plan)
+        return "empty_plan" if empty_plan
+        return "unaccepted_survivors" if counts[:survived].positive?
+        return "worker_errors" if counts[:error].positive?
 
         "clean"
       end

data/lib/active_mutator/reporter/stryker_json.rb

@@ -1,4 +1,5 @@
 require "json"
+require "fileutils"
 
 module ActiveMutator
   module Reporter
@@ -31,9 +32,13 @@ module ActiveMutator
         @out.print(Terminal::CHARS.fetch(result.status))
       end
 
-      def summary(results, invalid_count:)
+      # A zero-mutant report is valid schema output, so an empty plan writes the
+      # same file with no files/mutants; the flag is accepted for contract parity.
+      def summary(results, invalid_count:, empty_plan: false)
         report = build_report(results, invalid_count)
         path = File.join(@root, REPORT_PATH)
+        # An empty plan skips the baseline, which used to create this dir.
+        FileUtils.mkdir_p(File.dirname(path))
         AtomicFile.write(path, JSON.pretty_generate(report))
         @out.puts "", "", "Stryker report written to #{REPORT_PATH}"
       end

data/lib/active_mutator/reporter/terminal.rb

@@ -12,14 +12,21 @@ module ActiveMutator
         @out.print(CHARS.fetch(result.status))
       end
 
-      def summary(results, invalid_count:)
-        counts = results.group_by(&:status).transform_values(&:size)
+      # Every status key is present (zero when absent) so the block has the same
+      # shape on every run, including an empty plan.
+      def self.counts(results)
+        tallies = results.group_by(&:status).transform_values(&:size)
+        CHARS.keys.to_h { |status| [status, tallies.fetch(status, 0)] }
+      end
+
+      # `empty_plan: true` means a --since/--subject scope planned nothing: the
+      # count block still prints, but there is no score to report (#45).
+      def summary(results, invalid_count:, empty_plan: false)
+        counts = self.class.counts(results)
         @out.puts "", ""
-        CHARS.each_key do |status|
-          @out.puts "#{status}: #{counts.fetch(status, 0)}"
-        end
+        counts.each { |status, count| @out.puts "#{status}: #{count}" }
         @out.puts "invalid (discarded): #{invalid_count}"
-        @out.puts format("Mutation score: %.1f%%", score(counts) * 100)
+        @out.puts format("Mutation score: %.1f%%", score(counts) * 100) unless empty_plan
         print_group("Surviving mutants:", results.select { |r| r.status == :survived })
         print_group("Errored mutants (not detected):", results.select { |r| r.status == :error })
         print_group("Timed-out mutants (counted as detected):", results.select { |r| r.status == :timeout })

data/lib/active_mutator/runner.rb

@@ -2,6 +2,13 @@ require "json"
 
 module ActiveMutator
   class Runner
+    # What discovery saw, beyond the final subject list. `scanned_files` are
+    # root-relative source files after path expansion and excludes, minus
+    # spec_paths; `since_candidates` are the --since diff's files among them;
+    # `since_matched_all` are the since-covered subjects before --no-class-level
+    # drops class bodies. The last two feed the --allow-empty verdict (#46).
+    Discovery = Data.define(:subjects, :scanned_files, :since_candidates, :since_matched_all)
+
     def initialize(config, reporter: nil)
       @config = config
       @reporter = reporter || build_reporter
@@ -13,14 +20,24 @@ module ActiveMutator
       ClosureReload.cap = @config.class_level_closure_cap
       preload!
       preload_spec_helper!
-      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths)
-              .coverage_map(force: @config.force_baseline)
-      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
-      subjects = discover_subjects
+      discovery = discover
+      subjects = discovery.subjects
       analyses = subjects.map { |s| Engine.new.analyze(s) }
       mutations = analyses.flat_map(&:mutations)
       mutations = mutations.first(@config.max_mutants) if @config.max_mutants
       invalid_count = analyses.sum(&:invalid_count)
+      # Decide emptiness before the baseline: a scoped run that plans nothing
+      # has no use for a coverage map, and building one spawns the whole spec
+      # suite (#47).
+      if mutations.empty? && (@config.since || @config.subject_filter)
+        return debug_plan([], []) if @config.debug_plan
+
+        return empty_plan_exit(invalid_count, discovery)
+      end
+
+      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths)
+              .coverage_map(force: @config.force_baseline)
+      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
 
       fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
       ledger = AcceptedLedger.load(@config.root)
@@ -29,7 +46,6 @@ module ActiveMutator
 
       items, pre_results, phase1_ids = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
       return debug_plan(items, pre_results) if @config.debug_plan
-      return empty_plan_exit if mutations.empty? && (@config.since || @config.subject_filter)
 
       pre_results.each { |r| @reporter.on_result(r) }
       calibrators = if @config.adaptive_timeout
@@ -145,18 +161,51 @@ module ActiveMutator
     # the usual cause is a --since range or --subject filter that matched no
     # mutable code, or class-body code dropped by --no-class-level (#23 covers
     # the zero-subject case for explicit paths).
-    def empty_plan_exit
+    def empty_plan_exit(invalid_count, discovery)
+      @reporter.summary([], invalid_count: invalid_count, empty_plan: true)
       causes = []
       causes << "--since #{@config.since} matched no mutable code" if @config.since
       causes << "--subject #{@config.subject_filter} matched no subjects" if @config.subject_filter
       causes << "--no-class-level excludes class-body code" unless @config.class_level
       warn "active_mutator: no mutants planned (#{causes.join("; ")})"
-      return 0 if @config.allow_empty
+      unless @config.allow_empty
+        warn "active_mutator: exiting 1; pass --allow-empty if an empty plan is expected"
+        return 1
+      end
+
+      allow_empty_exit(discovery)
+    end
+
+    # --allow-empty forgives an empty plan only when the --since diff touched no
+    # candidate source file (docs-only, spec-only, excluded paths). A changed
+    # candidate that planned nothing is the case worth failing on, unless the
+    # only code it touched is class-body code that --no-class-level dropped.
+    # --subject alone has no diff to judge, so it stays an unconditional 0.
+    def allow_empty_exit(discovery)
+      return 0 unless @config.since
+
+      candidates = discovery.since_candidates
+      return 0 if candidates.empty?
 
-      warn "active_mutator: exiting 1; pass --allow-empty if an empty plan is expected"
+      if !@config.class_level && class_body_only?(discovery.since_matched_all, candidates)
+        warn "active_mutator: forgiving empty plan: changed lines are class-body code and --no-class-level is set"
+        return 0
+      end
+
+      warn "active_mutator: exiting 1; --allow-empty forgives an empty plan only when no candidate " \
+           "source file changed. Changed: #{candidates.join(", ")}"
       1
     end
 
+    # Every matched subject is a class body AND every candidate file has one:
+    # a candidate that matched nothing (comment-only edit, deletion) must not
+    # hide behind a class-body change in a different file. Candidates are
+    # non-empty here, so no matches at all fails the second test on its own.
+    def class_body_only?(subjects, candidates)
+      matched_files = subjects.map { |s| relative(s.file) }
+      subjects.all?(&:class_body?) && candidates.all? { |file| matched_files.include?(file) }
+    end
+
     # Single source of truth for lane/timeout/variable derivation, shared by
     # phase-1 planning and phase-2 escalation so the two never drift.
     def build_work_item(mutation, example_ids, map)
@@ -250,23 +299,38 @@ module ActiveMutator
       end
     end
 
-    def discover_subjects
+    def discover
       paths = @config.paths.empty? ? default_paths : @config.paths
-      subjects = paths
+      files = paths
         .flat_map { |p| expand_path_arg(p) }
         .uniq
         .reject { |file| excluded?(file) }
-        .sort.flat_map { |file| SubjectFinder.call(file) }
-      subjects = subjects.reject(&:class_body?) unless @config.class_level
+        .sort
+      scanned_files = files.map { |f| relative(f) }.reject { |rel| under_spec_paths?(rel) }
+      subjects = files.flat_map { |file| SubjectFinder.call(file) }
       if @config.subject_filter
         matcher = SubjectMatcher.new(@config.subject_filter)
         subjects = subjects.select { |s| matcher.match?(s.name) }
       end
+      since_candidates = []
       if @config.since
         filter = SinceFilter.new(ref: @config.since, root: @config.root)
         subjects = subjects.select { |s| filter.cover?(s) }
+        since_candidates = filter.changed_files & scanned_files
       end
-      subjects
+      # Class bodies drop out LAST so since_matched_all still knows about them.
+      since_matched_all = subjects
+      subjects = subjects.reject(&:class_body?) unless @config.class_level
+      Discovery.new(subjects: subjects, scanned_files: scanned_files,
+                    since_candidates: since_candidates, since_matched_all: since_matched_all)
+    end
+
+    def relative(file) = file.delete_prefix(@config.root.chomp("/") + "/")
+
+    # Scanned entries are files, so only the "inside this directory" test
+    # matters; the trailing slash keeps `spec` from swallowing `spec_tools/`.
+    def under_spec_paths?(rel)
+      @config.spec_paths.any? { |sp| rel.start_with?("#{sp.chomp("/")}/") }
     end
 
     # Positional args may be files or directories. Anything else is an error:
@@ -346,7 +410,7 @@ module ActiveMutator
     # MAINTENANCE: any future flag that narrows the mutant set below "every
     # subject in the scanned files" MUST be added to this nil-trigger list,
     # or scoped accept runs will clobber out-of-scope ledger entries (#24).
-    # --no-class-level drops every class_body subject (discover_subjects), so a
+    # --no-class-level drops every class_body subject (discover), so a
     # file's class-body fingerprint is absent even though the file is scanned;
     # without this guard its accepted ledger entry looks stale and gets pruned.
     def prune_scope(subjects)

data/lib/active_mutator/since_filter.rb

@@ -20,6 +20,15 @@ module ActiveMutator
       changed.reject { |_, lines| lines.empty? }
     end
 
+    # Every file the diff touched on the new side, including deletion-only
+    # files that `parse` drops (they add no lines, so nothing to cover, but
+    # the file still changed and must count as a --since candidate).
+    def self.touched_files(diff_text)
+      diff_text.each_line.filter_map do |line|
+        line.delete_prefix("+++ b/").strip if line.start_with?("+++ b/")
+      end.uniq
+    end
+
     def initialize(ref:, root:)
       @root = root
       diff = IO.popen(
@@ -28,15 +37,22 @@ module ActiveMutator
       raise Error, "git diff #{ref} failed" unless $?.success?
 
       @changed = self.class.parse(diff)
+      @touched = self.class.touched_files(diff)
       untracked = IO.popen(
         ["git", "-C", root, "ls-files", "--others", "--exclude-standard", "--", "*.rb"], &:read
       )
       # Untracked files are invisible to `git diff` but are agentic TDD's most
       # common case (brand-new file + spec). Whole-file sentinel: every line
       # counts as changed.
-      untracked.each_line { |l| @changed[l.strip] = :all unless l.strip.empty? }
+      untracked.split("\n").each { |l| @changed[l] = :all }
+      @touched |= @changed.keys
     end
 
+    # Root-relative paths of every .rb file the diff touched (tracked files,
+    # including deletion-only ones, plus untracked files). Pure accessor: no
+    # further git calls.
+    def changed_files = @touched
+
     def cover?(subject)
       lines = @changed[subject.file.delete_prefix("#{@root}/")]
       return false unless lines

data/lib/active_mutator/version.rb

@@ -1,3 +1,3 @@
 module ActiveMutator
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_mutator
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel John