mutaterb 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71841b126edbdca7f12d77aaca2622dde361a8011a49fbd2973cde656737c134
-  data.tar.gz: 2c45a913486f515d16ab0217d331b35e98f84f620a43b9a6496ad8c94681c940
+  metadata.gz: 82ad4fc719ac8b83a1857348b0be06c45fbb2995fbcf431d85fb2b2b52c74342
+  data.tar.gz: add794c175e4509c69fc293090c5c60c6f9493c5477cabeea89630863b5c1832
 SHA512:
-  metadata.gz: 1b716efda6a38584d538c4b76d82113be716dea2f466efd293afcef20d9b40aaf628a80ffd5aef8d3c8f80848314e3a6269bcb2877cf42d8c6c9b5bcb75dabe6
-  data.tar.gz: 24655446fcfc728007c10e89d7b8be5df414aaf99baf3d441f154add892c1dfcb59251570ca9747b132d606c167acb3ecb9e3ea71bcc230c8df6105dd912440c
+  metadata.gz: 1128b8a7cd0462d1aa9eff94dfeaec8e7950b59faed65cb7cd91a9731e2fbf7f18b225098cad6a1c43e576ce82ffd5b876d384e67f72ae735849fdbb6f8767dc
+  data.tar.gz: 47642ca53aa83eb67f9a5226a0452a6c6c4d8fdc4fe6369a02e4253c6c7a568d836a1be54f725dd6955097667489c6f46a25f2f38108a1c7e14ad252d5761042

data/README.md

@@ -31,6 +31,11 @@ and displays a summary: how many mutations were "killed" (caught by a test) and
 many "survived" (no test caught them — weak tests), with file, line, and related
 test(s) for each survivor.
 
+While it runs, it prints the baseline status and a live counter of mutants processed
+so far out of the total, so a long run never looks stuck. Pass `--verbose` to replace
+that counter with one line per mutant (file, line, mutation type, and result) as it is
+evaluated.
+
 ### Main flags
 
 | Flag | Description |
@@ -42,6 +47,7 @@ test(s) for each survivor.
 | `--framework FRAMEWORK` | `auto`, `rspec`, or `minitest` — forces the test framework instead of auto-detecting it |
 | `--mutation-types TYPES` | Mutation types to apply, comma-separated |
 | `--exit-zero` | Do not fail (exit 0) even if "survived" mutations exist |
+| `--verbose` | Print one line per mutant as it runs, instead of the default counter |
 | `--json-output PATH` | Export the results summary to a JSON file |
 | `--config PATH` | Use a config file other than `.mutaterb.yml` |
 

data/lib/mutaterb/cli.rb

@@ -45,9 +45,10 @@ module MutateRB
       end
       warn_ambiguous_frameworks(detection)
 
-      test_suite = build_test_suite(config, detection)
+      progress = ProgressReporter.new(verbose: config.verbose)
+      test_suite = build_test_suite(config, detection, progress)
       run = MutationRun.new(config: config, test_suite: test_suite)
-      run_mutations(run, test_suite, config) { interrupted }
+      run_mutations(run, test_suite, config, progress) { interrupted }
 
       run.finished_at = Time.now
       run.interrupted = interrupted
@@ -67,20 +68,31 @@ module MutateRB
            "(force one explicitly with --framework)"
     end
 
-    def build_test_suite(config, detection)
+    def build_test_suite(config, detection, progress)
       test_runner = TestRunner.new(config: config, project_type: detection.project_type,
                                    framework: detection.test_framework)
+      progress.start_baseline
       baseline_examples = test_runner.run_baseline(detection.test_files)
+      progress.finish_baseline
       TestSuite.from_baseline(project_type: detection.project_type, framework: detection.test_framework,
                               baseline_examples: baseline_examples)
     end
 
-    def run_mutations(run, test_suite, config)
+    def run_mutations(run, test_suite, config, progress)
       mutator = Mutator.new(config: config, test_suite: test_suite)
+      total = mutator.total_mutants
+      if total.zero?
+        warn "mutaterb: no mutants to run for the given scope"
+        return
+      end
+
+      progress.start_mutants(total)
       mutator.each_mutant do |mutant|
         run.add_mutant(mutant)
+        progress.mutant_finished(mutant)
         break if yield
       end
+      progress.finish_mutants
     end
   end
 end

data/lib/mutaterb/config.rb

@@ -12,11 +12,13 @@ module MutateRB
     DEFAULT_FILE_NAME = ".mutaterb.yml"
 
     attr_accessor :target_dir, :include_paths, :exclude_paths, :strictness,
-                  :mutation_types, :exit_on_survivors, :json_output_path, :test_framework
+                  :mutation_types, :exit_on_survivors, :json_output_path, :test_framework,
+                  :verbose
 
     def initialize(target_dir: ".", include_paths: [], exclude_paths: [],
                    strictness: :default, mutation_types: ALL_MUTATION_TYPES.dup,
-                   exit_on_survivors: true, json_output_path: nil, test_framework: :auto)
+                   exit_on_survivors: true, json_output_path: nil, test_framework: :auto,
+                   verbose: false)
       @target_dir = target_dir
       @include_paths = include_paths
       @exclude_paths = exclude_paths
@@ -25,6 +27,7 @@ module MutateRB
       @exit_on_survivors = exit_on_survivors
       @json_output_path = json_output_path
       @test_framework = test_framework
+      @verbose = verbose
       validate!
     end
 
@@ -48,7 +51,7 @@ module MutateRB
 
     def self.attributes_from_yaml(raw)
       known_keys = %w[target_dir include_paths exclude_paths strictness mutation_types
-                      exit_on_survivors json_output_path test_framework]
+                      exit_on_survivors json_output_path test_framework verbose]
       raw.each_key do |key|
         warn "mutaterb: ignoring unknown config key #{key.inspect}" unless known_keys.include?(key)
       end
@@ -67,7 +70,8 @@ module MutateRB
                         end,
         exit_on_survivors: raw.fetch("exit_on_survivors", true),
         json_output_path: raw["json_output_path"],
-        test_framework: raw.key?("test_framework") ? symbolize(raw["test_framework"], "test_framework") : :auto
+        test_framework: raw.key?("test_framework") ? symbolize(raw["test_framework"], "test_framework") : :auto,
+        verbose: raw.fetch("verbose", false)
       }
     end
     private_class_method :attributes_from_yaml
@@ -105,6 +109,7 @@ module MutateRB
       unknown = mutation_types - ALL_MUTATION_TYPES
       raise ConfigError, "unknown mutation_types: #{unknown.join(', ')}" unless unknown.empty?
       raise ConfigError, "exit_on_survivors must be true or false" unless [true, false].include?(exit_on_survivors)
+      raise ConfigError, "verbose must be true or false" unless [true, false].include?(verbose)
 
       validate_json_output_path!
     end

data/lib/mutaterb/flag_parser.rb

@@ -48,6 +48,7 @@ module MutateRB
         opts.on("--config PATH", "Use a config file other than .mutaterb.yml") do |v|
           flags[:config_path] = v
         end
+        opts.on("--verbose", "Print one line per mutant as it runs") { flags[:verbose] = true }
         opts.on("-h", "--help", "Show this help") do
           puts opts
           exit 0

data/lib/mutaterb/mutator.rb

@@ -19,17 +19,27 @@ module MutateRB
                                                    framework: test_suite.framework)
     end
 
+    # Total number of mutants this run will process, known upfront without running any
+    # test (FR-002, FR-008) — memoized alongside `candidates` (research.md #3).
+    def total_mutants
+      candidates.size
+    end
+
     # Yields each finished Mutant, one at a time.
     def each_mutant
-      source_files.each do |file|
-        candidates_for(file).each { |mutant| yield run_one(mutant) }
-      end
+      candidates.each { |mutant| yield run_one(mutant) }
     end
 
     private
 
     attr_reader :config, :test_suite, :test_runner
 
+    # Memoized: discovering candidates is pure parsing (no test execution), so computing
+    # it once upfront lets `total_mutants` be known before `each_mutant` starts (FR-002).
+    def candidates
+      @candidates ||= source_files.flat_map { |file| candidates_for(file) }
+    end
+
     def source_files
       Dir.glob(File.join(config.target_dir, "**", "*.rb"))
          .reject { |f| f.include?("/spec/") || f.include?("/test/") }

data/lib/mutaterb/progress_reporter.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # Live feedback for a run in progress (FR-001 to FR-005, FR-007): mutaterb used to print
+  # nothing between start and the final summary, so a long run was indistinguishable from a
+  # hang. A background thread ticks a status line on a timer, independent of whether the
+  # baseline suite or a single mutant's tests have actually finished (FR-003a) — the real work
+  # happens inside an opaque, blocking subprocess call, so this is the only way to keep the
+  # terminal changing during a slow phase.
+  class ProgressReporter
+    SPINNER_FRAMES = %w[| / - \\].freeze
+    TTY_TICK_INTERVAL = 0.3
+    NON_TTY_TICK_INTERVAL = 5
+
+    def initialize(io: $stdout, verbose: false, tick_interval: nil)
+      @io = io
+      @verbose = verbose
+      @tick_interval = tick_interval || (io.tty? ? TTY_TICK_INTERVAL : NON_TTY_TICK_INTERVAL)
+      @mutex = Mutex.new
+      @phase = :idle
+      @processed = 0
+      @total = 0
+      @phase_started_at = nil
+      @ticker_thread = nil
+    end
+
+    def start_baseline
+      @mutex.synchronize do
+        @phase = :baseline
+        @phase_started_at = Time.now
+      end
+      @io.puts "Running baseline tests..."
+      start_ticker
+    end
+
+    def finish_baseline
+      stop_ticker
+    end
+
+    def start_mutants(total)
+      @mutex.synchronize do
+        @phase = :mutating
+        @processed = 0
+        @total = total
+        @phase_started_at = Time.now
+      end
+      start_ticker unless @verbose
+    end
+
+    # In verbose mode, this line IS the progress indicator for the mutant loop (FR-005):
+    # the bare counter/ticker never runs, so there is nothing to interleave with it.
+    def mutant_finished(mutant)
+      if @verbose
+        print_mutant_line(mutant)
+      else
+        @mutex.synchronize { @processed += 1 }
+      end
+    end
+
+    def finish_mutants
+      stop_ticker
+      @mutex.synchronize { @phase = :done }
+    end
+
+    private
+
+    def print_mutant_line(mutant)
+      @io.puts "#{mutant.file_path}:#{mutant.line} [#{mutant.operator_type}] " \
+               "'#{mutant.original_fragment}' -> '#{mutant.mutated_fragment}' => #{mutant.status}"
+    end
+
+    def start_ticker
+      @ticker_thread = Thread.new { tick_loop }
+    end
+
+    def stop_ticker
+      return unless @ticker_thread
+
+      @ticker_thread.kill
+      @ticker_thread.join
+      @ticker_thread = nil
+      @io.puts if @io.tty?
+    end
+
+    # Never lets a rendering bug abort the real mutation run (Principio V): worst case, the
+    # ticker just stops drawing and the run continues silently, exactly like before this
+    # feature existed.
+    def tick_loop
+      loop do
+        sleep @tick_interval
+        draw
+      end
+    rescue StandardError
+      nil
+    end
+
+    def draw
+      line = current_line
+      return unless line
+
+      if @io.tty?
+        @io.print "\r#{line}"
+        @io.flush
+      else
+        @io.puts line
+      end
+    end
+
+    def current_line
+      @mutex.synchronize do
+        next nil unless @phase_started_at
+
+        elapsed = Time.now - @phase_started_at
+        spinner = SPINNER_FRAMES[(elapsed / @tick_interval).to_i % SPINNER_FRAMES.size]
+        case @phase
+        when :baseline
+          "Running baseline tests... (#{spinner} #{elapsed.round}s)"
+        when :mutating
+          "Mutating... #{@processed}/#{@total} (#{spinner} #{elapsed.round}s)"
+        end
+      end
+    end
+  end
+end

data/lib/mutaterb/reporter.rb

@@ -75,7 +75,8 @@ module MutateRB
         exclude_paths: c.exclude_paths,
         strictness: c.strictness.to_s,
         mutation_types: c.mutation_types.map(&:to_s),
-        exit_on_survivors: c.exit_on_survivors
+        exit_on_survivors: c.exit_on_survivors,
+        verbose: c.verbose
       }
     end
 

data/lib/mutaterb/test_adapters/minitest_adapter.rb

@@ -17,9 +17,14 @@ module MutateRB
       LINE_PATTERN = /^(\S+)\s*=\s*([\d.]+)\s*s\s*=\s*([.FES])/
       FILE_MARKER = "@@MUTATERB_FILE@@"
 
+      # Files are joined with `;`, not `&&`: `bin/rails test`/`ruby` exits non-zero whenever a
+      # test fails or errors, which is the normal case for a real project's suite — `&&` would
+      # silently stop the whole chain at the first failing file, dropping every file after it
+      # from the baseline. Nothing here reads the shell's exit status (TestRunner classifies
+      # purely from parsed output), so running every file regardless is safe.
       def self.command_for(files, project_type:)
         files.map { |file| "echo #{FILE_MARKER}#{Shellwords.escape(file)} && #{run_one(file, project_type)}" }
-             .join(" && ")
+             .join(" ; ")
       end
 
       def self.run_one(file, project_type)

data/lib/mutaterb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MutateRB
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/mutaterb.rb

@@ -18,6 +18,7 @@ require_relative "mutaterb/mutation_operators/boolean_literal_operator"
 require_relative "mutaterb/mutation_operators/nil_literal_operator"
 require_relative "mutaterb/mutation_operators/arithmetic_comparison_operator"
 require_relative "mutaterb/mutator"
+require_relative "mutaterb/progress_reporter"
 require_relative "mutaterb/reporter"
 require_relative "mutaterb/cli"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutaterb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - MarceloM47
@@ -76,6 +76,7 @@ files:
 - lib/mutaterb/mutation_operators/nil_literal_operator.rb
 - lib/mutaterb/mutation_run.rb
 - lib/mutaterb/mutator.rb
+- lib/mutaterb/progress_reporter.rb
 - lib/mutaterb/project_detector.rb
 - lib/mutaterb/reporter.rb
 - lib/mutaterb/test_adapters/minitest_adapter.rb