evilution 0.23.0 → 0.25.0

data/lib/evilution/parallel/work_queue.rb

@@ -21,31 +21,31 @@ class Evilution::Parallel::WorkQueue
     end
   end
 
-  def initialize(size:, hooks: nil, prefetch: 1, item_timeout: nil)
-    raise ArgumentError, "pool size must be a positive integer, got #{size.inspect}" unless size.is_a?(Integer) && size >= 1
-    raise ArgumentError, "prefetch must be a positive integer, got #{prefetch.inspect}" unless prefetch.is_a?(Integer) && prefetch >= 1
-    unless item_timeout.nil? || (item_timeout.is_a?(Numeric) && item_timeout.positive?)
-      raise ArgumentError, "item_timeout must be nil or a positive number, got #{item_timeout.inspect}"
-    end
-
+  def initialize(size:, hooks: nil, prefetch: 1, item_timeout: nil, worker_max_items: nil)
+    validate_init_args(size, prefetch, item_timeout, worker_max_items)
     @size = size
     @hooks = hooks
     @prefetch = prefetch
     @item_timeout = item_timeout
+    @worker_max_items = worker_max_items
     @worker_stats = []
   end
 
-  def map(items, &)
+  def map(items, &block)
     return [] if items.empty?
 
+    @block = block
+    @retired_workers = []
     worker_count = [@size, items.length].min
-    workers = spawn_workers(worker_count, &)
+    workers = spawn_workers(worker_count, &block)
 
     begin
       distribute_and_collect(items, workers)
     ensure
       shutdown_workers(workers)
-      @worker_stats = build_worker_stats(workers)
+      @worker_stats = @retired_workers + build_worker_stats(workers)
+      @block = nil
+      @retired_workers = nil
     end
   end
 
@@ -55,22 +55,64 @@ class Evilution::Parallel::WorkQueue
 
   private
 
-  def spawn_workers(count, &)
-    count.times.map do
-      cmd_read, cmd_write = IO.pipe
-      res_read, res_write = IO.pipe
+  def validate_init_args(size, prefetch, item_timeout, worker_max_items)
+    validate_positive_int!(:size, size)
+    validate_positive_int!(:prefetch, prefetch)
+    validate_optional_positive_number!(:item_timeout, item_timeout)
+    validate_optional_positive_int!(:worker_max_items, worker_max_items)
+  end
 
-      pid = Process.fork do
-        cmd_write.close
-        res_read.close
-        worker_loop(cmd_read, res_write, &)
-      end
+  def validate_positive_int!(name, value)
+    return if value.is_a?(Integer) && value >= 1
 
-      cmd_read.close
-      res_write.close
+    raise ArgumentError, "#{name} must be a positive integer, got #{value.inspect}"
+  end
+
+  def validate_optional_positive_int!(name, value)
+    return if value.nil? || (value.is_a?(Integer) && value.positive?)
+
+    raise ArgumentError, "#{name} must be nil or a positive integer, got #{value.inspect}"
+  end
+
+  def validate_optional_positive_number!(name, value)
+    return if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+    raise ArgumentError, "#{name} must be nil or a positive number, got #{value.inspect}"
+  end
+
+  def spawn_workers(count, &block)
+    count.times.map { |slot| spawn_one_worker(worker_index: slot, &block) }
+  end
+
+  # EV-kdns / GH #817: translate 0-based worker slot to parallel_tests'
+  # TEST_ENV_NUMBER convention ("" for slot 0, "2" for slot 1, ...). Rails
+  # apps interpolating TEST_ENV_NUMBER into database.yml get per-worker
+  # SQLite files, avoiding lock contention under jobs > 1.
+  def test_env_number_for(worker_index)
+    worker_index.zero? ? "" : (worker_index + 1).to_s
+  end
 
-      { pid: pid, cmd_write: cmd_write, res_read: res_read, items_completed: 0, pending: 0 }
+  def spawn_one_worker(worker_index:, &block)
+    cmd_read, cmd_write = IO.pipe
+    res_read, res_write = IO.pipe
+    # Marshal payloads are ASCII-8BIT; pipes default to text mode and may
+    # transcode according to their external/internal encodings (influenced by
+    # Encoding.default_external and/or Encoding.default_internal — Rails sets
+    # the latter to UTF-8), failing on bytes with no mapping. Force binmode on
+    # all four ends.
+    [cmd_read, cmd_write, res_read, res_write].each(&:binmode)
+
+    pid = Process.fork do
+      cmd_write.close
+      res_read.close
+      ENV["TEST_ENV_NUMBER"] = test_env_number_for(worker_index)
+      worker_loop(cmd_read, res_write, &block)
     end
+
+    cmd_read.close
+    res_write.close
+
+    { pid: pid, cmd_write: cmd_write, res_read: res_read, items_completed: 0, pending: 0, worker_index: worker_index }
   end
 
   def worker_loop(cmd_read, res_write, &block)
@@ -135,33 +177,109 @@ class Evilution::Parallel::WorkQueue
       end
 
       readable.each do |io|
-        alive = handle_result(io, io_to_worker[io], items, state)
+        alive = handle_result(io, io_to_worker[io], items, state, workers, io_to_worker, result_ios)
         result_ios.delete(io) unless alive
       end
     end
   end
 
-  def handle_result(io, worker, items, state)
+  def handle_result(io, worker, items, state, workers, io_to_worker, result_ios)
     message = read_result(io)
+    return handle_dead_worker(worker, state) if message.nil?
 
-    if message.nil?
-      state.first_error = Evilution::Error.new("worker process exited unexpectedly") if state.first_error.nil?
-      state.in_flight -= worker[:pending]
-      worker[:pending] = 0
-      return false
-    end
+    record_result(message, worker, state)
+    return false if recycle_and_dispatch(worker, items, state, workers, io_to_worker, result_ios)
+    return true if draining_for_recycle?(worker)
+
+    send_item(worker, items, state) if state.next_index < items.length && state.first_error.nil?
+    true
+  end
+
+  # Once worker hits K, stop dispatching so pending drains to 0; recycle fires
+  # on the next result. Prevents prefetch > 1 from refilling pending forever.
+  def draining_for_recycle?(worker)
+    @worker_max_items && worker[:items_completed] >= @worker_max_items && worker[:pending].positive?
+  end
 
+  def handle_dead_worker(worker, state)
+    state.first_error = Evilution::Error.new("worker process exited unexpectedly") if state.first_error.nil?
+    state.in_flight -= worker[:pending]
+    worker[:pending] = 0
+    false
+  end
+
+  def record_result(message, worker, state)
     index, status, value = message
     state.first_error = value if status == :error && state.first_error.nil?
     state.results[index] = value if status == :ok
     state.in_flight -= 1
     worker[:pending] -= 1
     worker[:items_completed] += 1
+  end
+
+  def recycle_and_dispatch(worker, items, state, workers, io_to_worker, result_ios)
+    return false unless should_recycle?(worker, state, items)
+
+    new_worker = recycle_worker(worker, workers, io_to_worker, result_ios)
+    send_item(new_worker, items, state) if state.next_index < items.length && state.first_error.nil?
+    true
+  end
+
+  def should_recycle?(worker, state, items)
+    return false unless @worker_max_items
+    return false if worker[:items_completed] < @worker_max_items
+    return false unless worker[:pending].zero?
+    return false unless state.next_index < items.length
+    return false unless state.first_error.nil?
 
-    send_item(worker, items, state) if state.next_index < items.length && state.first_error.nil?
     true
   end
 
+  def recycle_worker(old_worker, workers, io_to_worker, result_ios)
+    io_to_worker.delete(old_worker[:res_read])
+    result_ios.delete(old_worker[:res_read])
+    retire_worker(old_worker)
+
+    new_worker = spawn_one_worker(worker_index: old_worker[:worker_index], &@block)
+    workers[workers.index(old_worker)] = new_worker
+    io_to_worker[new_worker[:res_read]] = new_worker
+    result_ios << new_worker[:res_read]
+
+    new_worker
+  end
+
+  def retire_worker(worker)
+    begin
+      write_message(worker[:cmd_write], SHUTDOWN)
+    rescue Errno::EPIPE
+      nil
+    end
+
+    busy, wall = drain_worker_stats(worker)
+
+    worker[:cmd_write].close unless worker[:cmd_write].closed?
+    worker[:res_read].close unless worker[:res_read].closed?
+    begin
+      Process.wait(worker[:pid])
+    rescue Errno::ECHILD
+      nil
+    end
+
+    @retired_workers << WorkerStat.new(worker[:pid], worker[:items_completed], busy, wall)
+  end
+
+  def drain_worker_stats(worker)
+    return [0.0, 0.0] unless worker[:res_read].wait_readable(TIMING_GRACE_PERIOD)
+
+    message = read_result(worker[:res_read])
+    return [0.0, 0.0] if message.nil?
+
+    tag, busy_time, wall_time = message
+    return [0.0, 0.0] unless tag == STATS
+
+    [busy_time, wall_time]
+  end
+
   def send_item(worker, items, state)
     write_message(worker[:cmd_write], [state.next_index, items[state.next_index]])
     state.next_index += 1

data/lib/evilution/parallel_db_warning.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "erb"
+require "yaml"
+require_relative "../evilution"
+
+# EV-kdns / GH #817: nudge users running parallel jobs against SQLite to adopt
+# the parallel_tests convention. WorkQueue sets TEST_ENV_NUMBER per worker, but
+# that only helps if config/database.yml interpolates it into the database path.
+# Without per-worker DB files, concurrent workers pile up on one SQLite file and
+# surface ActiveRecord::StatementTimeout / SQLite3::BusyException — noise that
+# MutationExecutor demotes to :neutral but still wastes wall-clock time.
+module Evilution::ParallelDbWarning
+  DATABASE_YML = File.join("config", "database.yml")
+  MESSAGE = "[evilution] Parallel run (jobs > 1) detected with SQLite in " \
+            "config/database.yml. Interpolate ENV['TEST_ENV_NUMBER'] into the " \
+            "test database path for per-worker DB isolation. See README."
+
+  @warned_roots = {}
+  @mutex = Mutex.new
+
+  class << self
+    def warn_if_sqlite_parallel(config, output: $stderr, root: Dir.pwd)
+      return unless config.jobs > 1
+      return unless sqlite_in_test_config?(root)
+
+      @mutex.synchronize do
+        return if @warned_roots[root]
+
+        @warned_roots[root] = true
+      end
+
+      output.puts(MESSAGE)
+    end
+
+    def reset!
+      @mutex.synchronize { @warned_roots.clear }
+    end
+
+    private
+
+    # Only the `test` section matters for parallel mutation runs. Scanning the
+    # whole file would false-positive when dev/prod use SQLite but test uses
+    # Postgres/MySQL. Parse failures (ERB errors, custom helpers, anchor
+    # gymnastics) fall back to "no warning" rather than guessing.
+    def sqlite_in_test_config?(root)
+      path = File.join(root, DATABASE_YML)
+      return false unless File.exist?(path)
+
+      parsed = parse_database_yml(path)
+      return false unless parsed.is_a?(Hash)
+
+      test_config = parsed["test"]
+      return false unless test_config.is_a?(Hash)
+
+      adapter = test_config["adapter"]
+      adapter.is_a?(String) && adapter.downcase.include?("sqlite")
+    end
+
+    def parse_database_yml(path)
+      content = File.read(path)
+      rendered = ERB.new(content).result
+      YAML.safe_load(rendered, aliases: true)
+    rescue StandardError, SyntaxError
+      nil
+    end
+  end
+end

data/lib/evilution/reporter/cli.rb

@@ -7,6 +7,17 @@ class Evilution::Reporter::CLI
 
   def call(summary)
     lines = []
+    append_metrics(lines, summary)
+    append_sections(lines, summary)
+    lines << ""
+    lines << "[TRUNCATED] Stopped early due to --fail-fast" if summary.truncated?
+    lines << result_line(summary)
+    lines.join("\n")
+  end
+
+  private
+
+  def append_metrics(lines, summary)
     lines << header
     lines << SEPARATOR
     lines << ""
@@ -16,20 +27,18 @@ class Evilution::Reporter::CLI
     lines << efficiency_line(summary) if summary.duration.positive?
     peak = summary.peak_memory_mb
     lines << peak_memory_line(peak) if peak
+  end
+
+  def append_sections(lines, summary)
     append_survived(lines, summary)
     append_neutral(lines, summary)
     append_equivalent(lines, summary)
+    append_unresolved(lines, summary)
+    append_unparseable(lines, summary)
     append_errors(lines, summary)
     append_disabled(lines, summary)
-    lines << ""
-    lines << "[TRUNCATED] Stopped early due to --fail-fast" if summary.truncated?
-    lines << result_line(summary)
-
-    lines.join("\n")
   end
 
-  private
-
   def append_survived(lines, summary)
     gaps = summary.coverage_gaps
     return unless gaps.any?
@@ -55,6 +64,22 @@ class Evilution::Reporter::CLI
     summary.equivalent_results.each { |result| lines << format_neutral(result) }
   end
 
+  def append_unresolved(lines, summary)
+    return unless summary.unresolved_results.any?
+
+    lines << ""
+    lines << "Unresolved mutations (no test file resolved):"
+    summary.unresolved_results.each { |result| lines << format_neutral(result) }
+  end
+
+  def append_unparseable(lines, summary)
+    return unless summary.unparseable_results.any?
+
+    lines << ""
+    lines << "Unparseable mutations (mutated source did not parse):"
+    summary.unparseable_results.each { |result| lines << format_neutral(result) }
+  end
+
   def append_errors(lines, summary)
     errored = summary.results.select(&:error?)
     return if errored.empty?
@@ -90,14 +115,15 @@ class Evilution::Reporter::CLI
             "#{summary.survived} survived, #{summary.timed_out} timed out"
     parts += ", #{summary.neutral} neutral" if summary.neutral.positive?
     parts += ", #{summary.equivalent} equivalent" if summary.equivalent.positive?
+    parts += ", #{summary.unresolved} unresolved" if summary.unresolved.positive?
+    parts += ", #{summary.unparseable} unparseable" if summary.unparseable.positive?
     parts += ", #{summary.skipped} skipped" if summary.skipped.positive?
     parts
   end
 
   def score_line(summary)
-    denominator = summary.total - summary.errors - summary.neutral - summary.equivalent
     score_pct = format_pct(summary.score)
-    "Score: #{score_pct} (#{summary.killed}/#{denominator})"
+    "Score: #{score_pct} (#{summary.killed}/#{summary.score_denominator})"
   end
 
   def duration_line(summary)
@@ -118,8 +144,9 @@ class Evilution::Reporter::CLI
                operators = gap.operator_names.join(", ")
                "  #{location} (#{gap.subject_name}) [#{gap.count} mutations: #{operators}]"
              end
-    diff_lines = gap.primary_diff.split("\n").map { |l| "    #{l}" }.join("\n")
-    "#{header}\n#{diff_lines}"
+    body = gap.mutation_results.first.mutation.unified_diff || gap.primary_diff
+    indented = body.split("\n").map { |l| "    #{l}" }.join("\n")
+    "#{header}\n#{indented}"
   end
 
   def format_neutral(result)

data/lib/evilution/reporter/html/assets/style.css

@@ -0,0 +1,85 @@
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #0d1117; color: #c9d1d9; padding: 2rem; max-width: 1200px; margin: 0 auto; }
+header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 2rem; }
+h1 { font-size: 1.5rem; color: #f0f6fc; }
+.version { color: #8b949e; font-weight: normal; font-size: 0.9rem; }
+.score-badge { font-size: 1.8rem; font-weight: bold; padding: 0.3rem 1rem; border-radius: 8px; }
+.score-high { background: #1a4731; color: #3fb950; }
+.score-medium { background: #4a3a10; color: #d29922; }
+.score-low { background: #4a1a1a; color: #f85149; }
+.summary-cards { display: flex; gap: 1rem; flex-wrap: wrap; margin-bottom: 2rem; }
+.card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 1rem 1.2rem; text-align: center; min-width: 100px; }
+.card-value { display: block; font-size: 1.4rem; font-weight: bold; color: #f0f6fc; }
+.card-label { display: block; font-size: 0.75rem; color: #8b949e; margin-top: 0.2rem; text-transform: uppercase; }
+.card-killed { border-color: #238636; }
+.card-survived { border-color: #da3633; }
+.truncation-notice { background: #4a3a10; border: 1px solid #d29922; color: #d29922; padding: 0.75rem 1rem; border-radius: 8px; margin-bottom: 2rem; }
+.file-section { background: #161b22; border: 1px solid #30363d; border-radius: 8px; margin-bottom: 1.5rem; overflow: hidden; }
+.file-header { display: flex; justify-content: space-between; align-items: center; padding: 0.75rem 1rem; background: #1c2129; border-bottom: 1px solid #30363d; font-size: 0.9rem; }
+.file-path { color: #58a6ff; font-family: monospace; }
+.file-stats { color: #8b949e; font-size: 0.8rem; font-weight: normal; }
+.mutation-map { padding: 0.5rem 1rem; }
+.map-line { display: flex; align-items: center; gap: 0.75rem; padding: 0.25rem 0.5rem; border-radius: 4px; font-size: 0.85rem; font-family: monospace; }
+.map-line.killed { color: #3fb950; }
+.map-line.survived { color: #f85149; }
+.map-line.timeout { color: #d29922; }
+.map-line.error { color: #f85149; }
+.map-line.neutral { color: #8b949e; }
+.map-line.equivalent { color: #8b949e; }
+.map-line.unresolved { color: #8b949e; }
+.map-line.unparseable { color: #8b949e; }
+.line-number { min-width: 60px; color: #8b949e; }
+.operator { flex: 1; }
+.status-badge { font-size: 0.7rem; padding: 0.1rem 0.5rem; border-radius: 10px; text-transform: uppercase; font-weight: bold; }
+.status-badge.killed { background: #1a4731; }
+.status-badge.survived { background: #4a1a1a; }
+.status-badge.timeout { background: #4a3a10; }
+.status-badge.neutral { background: #21262d; }
+.status-badge.equivalent { background: #21262d; }
+.status-badge.error { background: #4a3a10; }
+.status-badge.unresolved { background: #21262d; }
+.status-badge.unparseable { background: #21262d; }
+.survived-details { border-top: 1px solid #30363d; padding: 1rem; }
+.survived-details h3 { color: #f85149; font-size: 0.9rem; margin-bottom: 0.75rem; }
+.survived-entry { background: #1c1a1a; border: 1px solid #4a1a1a; border-radius: 6px; padding: 0.75rem; margin-bottom: 0.75rem; }
+.survived-header { display: flex; justify-content: space-between; margin-bottom: 0.5rem; font-size: 0.85rem; }
+.survived-header .operator { color: #f85149; font-weight: bold; }
+.survived-header .location { color: #8b949e; font-family: monospace; }
+.diff { background: #0d1117; border-radius: 4px; padding: 0.5rem 0.75rem; font-size: 0.8rem; overflow-x: auto; line-height: 1.5; }
+.diff-removed { color: #f85149; display: block; }
+.diff-added { color: #3fb950; display: block; }
+.suggestion { color: #d29922; font-size: 0.8rem; margin-top: 0.5rem; font-style: italic; }
+.coverage-gap { border: 1px solid #30363d; border-radius: 6px; padding: 0.75rem; margin-bottom: 0.75rem; background: #161b22; }
+.gap-header { display: flex; align-items: center; gap: 0.75rem; margin-bottom: 0.5rem; font-size: 0.85rem; padding-bottom: 0.5rem; border-bottom: 1px solid #21262d; }
+.gap-header .location { color: #58a6ff; font-family: monospace; }
+.gap-count { background: #4a1a1a; color: #f85149; font-size: 0.7rem; padding: 0.1rem 0.5rem; border-radius: 10px; font-weight: bold; }
+.operator-tag { background: #21262d; color: #8b949e; font-size: 0.7rem; padding: 0.1rem 0.4rem; border-radius: 4px; font-family: monospace; }
+.empty { color: #8b949e; text-align: center; padding: 2rem; }
+.baseline-comparison { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 1rem; margin-bottom: 2rem; }
+.baseline-comparison h2 { font-size: 1rem; color: #f0f6fc; margin-bottom: 0.75rem; }
+.comparison-scores { display: flex; gap: 2rem; font-size: 0.9rem; }
+.delta-positive { color: #3fb950; font-weight: bold; }
+.delta-negative { color: #f85149; font-weight: bold; }
+.delta-neutral { color: #8b949e; font-weight: bold; }
+.error-details { border-top: 1px solid #30363d; padding: 1rem; }
+.error-details h3 { color: #d29922; font-size: 0.9rem; margin-bottom: 0.75rem; }
+.error-entry { background: #1c1a10; border: 1px solid #4a3a10; border-radius: 6px; padding: 0.75rem; margin-bottom: 0.75rem; }
+.error-header { display: flex; justify-content: space-between; margin-bottom: 0.5rem; font-size: 0.85rem; }
+.error-header .operator { color: #d29922; font-weight: bold; }
+.error-header .location { color: #8b949e; font-family: monospace; }
+.error-message { background: #0d1117; border-radius: 4px; padding: 0.5rem 0.75rem; font-size: 0.8rem; color: #f85149; margin-top: 0.5rem; white-space: pre-wrap; overflow-x: auto; }
+.unresolved-details { border-top: 1px solid #30363d; padding: 1rem; }
+.unresolved-details h3 { color: #8b949e; font-size: 0.9rem; margin-bottom: 0.75rem; }
+.unresolved-details ul { list-style: none; }
+.unresolved-details li { font-size: 0.85rem; padding: 0.2rem 0; color: #8b949e; }
+.unresolved-details .operator { color: #c9d1d9; font-family: monospace; margin-right: 0.75rem; }
+.unresolved-details .location { font-family: monospace; }
+.unparseable-details { border-top: 1px solid #30363d; padding: 1rem; }
+.unparseable-details h3 { color: #8b949e; font-size: 0.9rem; margin-bottom: 0.75rem; }
+.unparseable-details ul { list-style: none; }
+.unparseable-details li { font-size: 0.85rem; padding: 0.2rem 0; color: #8b949e; }
+.unparseable-details .operator { color: #c9d1d9; font-family: monospace; margin-right: 0.75rem; }
+.unparseable-details .location { font-family: monospace; }
+.survived-entry.regression { border-color: #f85149; background: #2a1010; }
+.regression-badge { background: #da3633; color: #fff; font-size: 0.65rem; padding: 0.1rem 0.4rem; border-radius: 4px; margin-left: 0.5rem; text-transform: uppercase; font-weight: bold; }
+footer { text-align: center; color: #484f58; font-size: 0.75rem; margin-top: 2rem; padding-top: 1rem; border-top: 1px solid #21262d; }

data/lib/evilution/reporter/html/baseline_keys.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "namespace"
+
+class Evilution::Reporter::HTML::BaselineKeys
+  def initialize(baseline)
+    @keys = build(baseline)
+  end
+
+  def regression?(mutation)
+    return false if @keys.nil?
+
+    !@keys.include?(key_for(mutation))
+  end
+
+  private
+
+  def build(baseline)
+    return nil unless baseline
+
+    survived = baseline["survived"] || []
+    survived.to_set { |m| [m["operator"], m["file"], m["line"], m["subject"]] }
+  end
+
+  def key_for(mutation)
+    [mutation.operator_name, mutation.file_path, mutation.line, mutation.subject.name]
+  end
+end

data/lib/evilution/reporter/html/diff_formatter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "namespace"
+require_relative "escape"
+
+module Evilution::Reporter::HTML::DiffFormatter
+  module_function
+
+  def call(diff)
+    diff.split("\n").map { |line| format_line(line) }.join("\n")
+  end
+
+  def format_line(line)
+    css_class = line_class(line)
+    %(<span class="#{css_class}">#{Evilution::Reporter::HTML::Escape.call(line)}</span>)
+  end
+
+  def line_class(line)
+    if line.start_with?("- ")
+      "diff-removed"
+    elsif line.start_with?("+ ")
+      "diff-added"
+    else
+      ""
+    end
+  end
+end

data/lib/evilution/reporter/html/escape.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "cgi"
+require_relative "namespace"
+
+module Evilution::Reporter::HTML::Escape
+  module_function
+
+  def call(text)
+    CGI.escapeHTML(text.to_s)
+  end
+end

data/lib/evilution/reporter/html/namespace.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "../../reporter"
+
+# rubocop:disable Style/OneClassPerFile
+class Evilution::Reporter::HTML # rubocop:disable Lint/EmptyClass
+end
+
+module Evilution::Reporter::HTML::Sections
+end
+# rubocop:enable Style/OneClassPerFile

data/lib/evilution/reporter/html/report.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "section"
+require_relative "stylesheet"
+require_relative "baseline_keys"
+require_relative "sections/header"
+require_relative "sections/summary_cards"
+require_relative "sections/baseline_comparison"
+require_relative "sections/truncation_notice"
+require_relative "sections/file_section"
+
+class Evilution::Reporter::HTML::Report < Evilution::Reporter::HTML::Section
+  template "report"
+
+  def initialize(summary, baseline:, baseline_keys:, suggestion:)
+    @summary = summary
+    @baseline = baseline
+    @baseline_keys = baseline_keys
+    @suggestion = suggestion
+  end
+
+  private
+
+  def stylesheet
+    Evilution::Reporter::HTML::Stylesheet.call
+  end
+
+  def header
+    Evilution::Reporter::HTML::Sections::Header.new(@summary).render
+  end
+
+  def summary_cards
+    Evilution::Reporter::HTML::Sections::SummaryCards.new(@summary).render
+  end
+
+  def baseline_comparison
+    Evilution::Reporter::HTML::Sections::BaselineComparison.render_if(@baseline, @summary)
+  end
+
+  def truncation_notice
+    Evilution::Reporter::HTML::Sections::TruncationNotice.render_if(@summary)
+  end
+
+  def file_sections
+    files = group_by_file(@summary.results)
+    return '<p class="empty">No mutations generated.</p>' if files.empty?
+
+    files.map { |path, results| file_section(path, results) }.join("\n")
+  end
+
+  def file_section(path, results)
+    Evilution::Reporter::HTML::Sections::FileSection.new(
+      path, results,
+      suggestion: @suggestion,
+      baseline_keys: @baseline_keys
+    ).render
+  end
+
+  def group_by_file(results)
+    grouped = {}
+    results.each do |result|
+      path = result.mutation.file_path
+      grouped[path] ||= []
+      grouped[path] << result
+    end
+    grouped.sort_by { |path, _| path }.to_h
+  end
+end

data/lib/evilution/reporter/html/section.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "namespace"
+require_relative "escape"
+
+class Evilution::Reporter::HTML::Section
+  TEMPLATE_DIR = File.expand_path("templates", __dir__)
+
+  def self.template(name)
+    path = File.join(TEMPLATE_DIR, "#{name}.html.erb")
+    erb = ERB.new(File.read(path), trim_mode: "-")
+    erb.def_method(self, "render")
+  end
+
+  private
+
+  def h(text)
+    Evilution::Reporter::HTML::Escape.call(text)
+  end
+end