mutineer 0.11.1 → 0.11.3

data/lib/mutineer/rails_worker_db.rb

@@ -1,33 +1,32 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # #26/#27 Phase 2b (U5) — per-worker database isolation for the daemon path.
+  # Per-worker database isolation for the daemon path.
   #
-  # Loaded APP-SIDE by {DaemonServer} (a sibling gem file, pulled in by absolute path
-  # so it bypasses the app bundle — the same trick {DaemonClient} uses to run
-  # `daemon_server.rb` under a bundle that has no mutineer). It uses the app's OWN
-  # already-booted ActiveRecord and NEVER `require "active_record"` (R10/KTD-8): every
+  # Loaded APP-SIDE by {DaemonServer} (a sibling gem file, pulled in by absolute
+  # path so it bypasses the app bundle, the same trick {DaemonClient} uses to run
+  # `daemon_server.rb` under a bundle that has no mutineer). It uses the app's
+  # OWN already-booted ActiveRecord and NEVER `require "active_record"`: every
   # method that touches AR first confirms {available?}, so the daemon core stays
   # framework-agnostic and the gem keeps its zero-runtime-dependency promise.
   #
-  # Isolation model (KTD-7): each parallel worker gets its OWN database so concurrent
-  # forks can't clobber each other's transactional fixtures (the measured #26
-  # corruption). {after_fork} runs inside a freshly-forked child and points that
-  # child's connection at the worker's database BEFORE any test loads; transactional
-  # fixtures then repopulate that isolated database per test.
+  # Isolation model: each parallel worker gets its OWN database so concurrent
+  # forks cannot clobber each other's transactional fixtures. {after_fork} runs
+  # inside a freshly-forked child and points that child's connection at the
+  # worker's database BEFORE any test loads; transactional fixtures then
+  # repopulate that isolated database per test.
   #
-  # Scope: this pass ships the **SQLite** adapter (per-worker file, hermetic,
-  # spike-proven). Postgres per-worker DBs (`CREATE DATABASE <db>-<worker>`) are not
-  # implemented yet; a non-SQLite config raises a clear NotImplementedError rather
-  # than silently mis-routing.
+  # Scope: SQLite adapter only (per-worker file, hermetic). Postgres per-worker
+  # DBs (`CREATE DATABASE <db>-<worker>`) are not implemented yet; a non-SQLite
+  # config raises a clear NotImplementedError rather than silently mis-routing.
   #
-  # Honest limit (KTD-5): routing failures surface as `error` via {verify_connection!}.
-  # Re-raising an AR error that fires *inside a test body* past Minitest (so an in-test
-  # DB failure is `error`, not `killed`) is only observable under concurrent load and
-  # is deferred to U6 with the parallel gate — noted, not silently skipped.
+  # Routing failures surface as `error` via {verify_connection!}. Tagging an
+  # in-test DB failure as `error` (not `killed`) is only observable under
+  # concurrent load and is not yet implemented.
   module RailsWorkerDb
-    # True when the app has ActiveRecord loaded — the only condition under which any
-    # other method here may touch AR. Never triggers an autoload/require of AR itself.
+    # True when the app has ActiveRecord loaded. The only condition under which
+    # any other method here may touch AR. Never triggers an autoload/require of
+    # AR itself.
     #
     # @return [Boolean]
     def self.available?
@@ -35,8 +34,9 @@ module Mutineer
     end
 
     # Derive a per-worker database path from a base path by inserting `-<worker>`
-    # before the extension. Pure string transform (no AR) so it is unit-testable in
-    # the zero-dep suite. `storage/test.sqlite3`, worker 1 -> `storage/test-1.sqlite3`.
+    # before the extension. Pure string transform (no AR) so it is unit-testable
+    # in the zero-dep suite. `storage/test.sqlite3`, worker 1 ->
+    # `storage/test-1.sqlite3`.
     #
     # @param database [String] the base database path.
     # @param worker [Integer] the worker slot index (0..N-1).
@@ -47,9 +47,9 @@ module Mutineer
     end
 
     # Build the AR connection config for one worker by copying the app's current
-    # (default test) config and swapping in the per-worker database path. SQLite only
-    # this pass — a non-SQLite adapter raises so the SQLite-first scope fails loud
-    # instead of mis-routing (Postgres is U10).
+    # (default test) config and swapping in the per-worker database path. SQLite
+    # only this pass: a non-SQLite adapter raises so the SQLite-first scope fails
+    # loud instead of mis-routing.
     #
     # @param worker [Integer] the worker slot index.
     # @return [Hash] a symbol-keyed AR configuration hash for the worker database.
@@ -57,16 +57,15 @@ module Mutineer
     def self.worker_db_config(worker)
       hash    = ActiveRecord::Base.connection_db_config.configuration_hash
       adapter = hash[:adapter].to_s
-      # U10 seam: the config-SHAPING below (per_worker_config) is already
-      # adapter-general — it derives correct SQLite *and* Postgres worker-DB names.
-      # What's gated is runtime PROVISIONING: SQLite files are created on connect,
-      # but Postgres needs an explicit `CREATE DATABASE` per worker (U10). Until that
-      # lands, refuse non-SQLite loudly rather than route to a database that doesn't
-      # exist until Postgres worker creation is implemented.
+      # Config shaping (per_worker_config) is already adapter-general: it derives
+      # correct SQLite and Postgres worker-DB names. What is gated is runtime
+      # provisioning: SQLite files are created on connect, but Postgres needs an
+      # explicit `CREATE DATABASE` per worker. Until that lands, refuse non-SQLite
+      # loudly rather than route to a database that does not exist.
       unless adapter.start_with?("sqlite")
         raise NotImplementedError,
               "worker-DB isolation currently provisions SQLite only (got adapter #{adapter.inspect}); " \
-              "Postgres per-worker provisioning is U10 (#26/#35) — use a SQLite test DB, or drop --jobs."
+              "Postgres per-worker provisioning is not yet supported. Use a SQLite test DB, or drop --jobs."
       end
 
       per_worker_config(hash, worker)
@@ -74,10 +73,10 @@ module Mutineer
 
     # Pure config-shaping (no AR): given a connection config hash, return the
     # per-worker variant with its database swapped to the worker's own name.
-    # Adapter-general — SQLite (`storage/test.sqlite3` → `storage/test-<w>.sqlite3`)
-    # and Postgres (`myapp_test` → `myapp_test-<w>`, Rails `parallelize` naming) both
-    # fall out of {worker_database_path}. Extracted + unit-tested so the Postgres
-    # SHAPE is proven ready for U10 without a live database.
+    # Adapter-general: SQLite (`storage/test.sqlite3` -> `storage/test-<w>.sqlite3`)
+    # and Postgres (`myapp_test` -> `myapp_test-<w>`, Rails `parallelize` naming)
+    # both fall out of {worker_database_path}. Extracted and unit-tested so the
+    # Postgres shape is proven ready without a live database.
     #
     # @param config_hash [Hash] a connection config hash (symbol or string keys).
     # @param worker [Integer] the worker slot index.
@@ -94,11 +93,12 @@ module Mutineer
       hash.merge(database: worker_database_path(database, worker))
     end
 
-    # Child-side (after fork): route this process's ActiveRecord at the worker's own
-    # database and confirm it is reachable, so a routing failure reads as `error`
-    # (via the daemon's child rescue) rather than a false verdict. Loads the schema
-    # into the worker database when a schema path is given (idempotent — schema.rb
-    # runs with `force: true`), covering a fresh worker file.
+    # Child-side (after fork): route this process's ActiveRecord at the worker's
+    # own database and confirm it is reachable, so a routing failure reads as
+    # `error` (via the daemon's child rescue) rather than a false verdict. Loads
+    # the schema into the worker database when a schema path is given
+    # (idempotent: schema.rb runs with `force: true`), covering a fresh worker
+    # file.
     #
     # @param worker [Integer] the worker slot index.
     # @param schema_path [String, nil] absolute path to `db/schema.rb`, or nil to skip.
@@ -126,8 +126,9 @@ module Mutineer
       $stdout = original
     end
 
-    # Force a round-trip to the freshly-routed connection so a broken route fails HERE
-    # (→ `error`) instead of later masquerading as a test failure (→ false `killed`).
+    # Force a round-trip to the freshly-routed connection so a broken route fails
+    # HERE (→ `error`) instead of later masquerading as a test failure
+    # (→ false `killed`).
     #
     # @return [void]
     def self.verify_connection!

data/lib/mutineer/reporter.rb

@@ -7,7 +7,7 @@ require_relative "mutation"
 
 module Mutineer
   # Renders an AggregateResult: the summary block, mutation score, and per-file
-  # survivor diffs. Stream discipline (R14): the report goes to `out` (stdout),
+  # survivor diffs. Stream discipline: the report goes to `out` (stdout),
   # diagnostics/warnings go to `err` (stderr), so `mutineer ... > report.txt`
   # captures only the report.
   #
@@ -19,7 +19,7 @@ module Mutineer
       @source_map = source_map
     end
 
-    # Single entry point (R20/R21). Branches on `format` ("human" | "json") and
+    # Single entry point. Branches on `format` ("human" | "json" | "html") and
     # routes the rendered report to `output` (a file, with a stderr confirmation)
     # or to `out`. Diagnostics always go to `err`.
     def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil, baseline: nil)
@@ -90,10 +90,9 @@ module Mutineer
 
     private
 
-    # Canonical machine-readable schema (KTD7). survivors/no_coverage are sorted
-    # by (file, line, operator) so output is byte-stable regardless of --jobs
-    # worker finish order (R22).
-    # Renders the JSON report.
+    # Canonical machine-readable schema. survivors/no_coverage are sorted by
+    # (file, line, operator) so output is byte-stable regardless of --jobs
+    # worker finish order.
     #
     # @api private
     # @param baseline [Mutineer::Baseline::Delta, nil] baseline delta.
@@ -101,7 +100,7 @@ module Mutineer
     def json_report(baseline = nil)
       killed = @agg.killed_count
       survived = @agg.survived_count
-      # C8: null (not 0.0) on an empty denominator, matching the nil-vs-0.0
+      # null (not 0.0) on an empty denominator, matching the nil-vs-0.0
       # discipline in AggregateResult; and the SAME rounding as the human report
       # (one run must not yield two scores by --format).
       score = @agg.mutation_score
@@ -121,31 +120,31 @@ module Mutineer
                        .sort_by { |h| [h[:file], h[:line], h[:operator]] },
         no_coverage: @agg.results.select(&:no_coverage?).map { |r| no_coverage_json(r) }
                          .sort_by { |h| [h[:file], h[:line]] },
-        # #9: same shape as no_coverage; additive key.
+        # Same shape as no_coverage; additive key.
         uncapturable: @agg.results.select(&:uncapturable?).map { |r| no_coverage_json(r) }
                           .sort_by { |h| [h[:file], h[:line]] },
-        # #10: equivalent mutants the user suppressed — emitted with their stable
-        # id so the user can audit what is silenced (and copy ids for survivors
-        # they want to add). Excluded from the score; never in `survivors`.
+        # Equivalent mutants the user suppressed: emitted with their stable id so
+        # the user can audit what is silenced (and copy ids for survivors they
+        # want to add). Excluded from the score; never in `survivors`.
         ignored: @agg.results.select(&:ignored?).map { |r| ignored_json(r) }
                      .sort_by { |h| [h[:file], h[:line], h[:operator]] },
-        # #11: per-source breakdown (additive; #13 consumes it). Sorted by file so
+        # Per-source breakdown (additive; baseline consumes it). Sorted by file so
         # output is byte-stable. Reuses AggregateResult via by_source.
         per_source: @agg.by_source.map { |file, agg| per_source_json(file, agg) }
                         .sort_by { |h| h[:file] }
       }
-      # #13: additive baseline-delta block, present only with --baseline. Existing
+      # Additive baseline-delta block, present only with --baseline. Existing
       # consumers ignore the extra key; schema_version stays 1.1.
       doc[:baseline] = baseline_json(baseline) if baseline
       "#{JSON.generate(doc)}\n"
     end
 
-    # #23: one self-contained HTML file (inline CSS, no external assets) — the
-    # overall score + summary counts, a per-source table, and every surviving
-    # mutant with its stable id and diff. All source/diff/identifier text is
-    # HTML-escaped (CGI.escapeHTML) so a `<`/`>` in source can never break the
-    # markup. Reuses survivor_json/per_source_json so one run yields one set of
-    # facts regardless of --format.
+    # One self-contained HTML file (inline CSS, no external assets): the overall
+    # score + summary counts, a per-source table, and every surviving mutant with
+    # its stable id and diff. All source/diff/identifier text is HTML-escaped
+    # (CGI.escapeHTML) so a `<`/`>` in source can never break the markup. Reuses
+    # survivor_json/per_source_json so one run yields one set of facts regardless
+    # of --format.
     def html_report
       score = @agg.mutation_score
       survivors = @agg.surviving_mutants.map { |r| survivor_json(r) }
@@ -251,9 +250,9 @@ module Mutineer
     # HTML-escapes any text destined for the document (stdlib CGI).
     def esc(text) = CGI.escapeHTML(text.to_s)
 
-    # #13: the same delta facts the human report prints, for dashboards. new_survivors
+    # The same delta facts the human report prints, for dashboards. new_survivors
     # reuse the ignored_json shape (subject/file/line/operator/token/id) and sort
-    # byte-stably so output doesn't depend on --jobs finish order.
+    # byte-stably so output does not depend on --jobs finish order.
     def baseline_json(delta)
       {
         regressed: delta.regressed,
@@ -300,7 +299,7 @@ module Mutineer
         file: file,
         line: start_line,
         operator: m.operator.to_s,
-        # #10: the stable, copy-pasteable id (next to the human-readable token) so a
+        # The stable, copy-pasteable id (next to the human-readable token) so a
         # user can paste it straight into .mutineer.yml `ignore:`.
         id: result.id,
         token: token,
@@ -308,7 +307,7 @@ module Mutineer
       }
     end
 
-    # An entry under the JSON `ignored:` key — what the user already suppressed.
+    # An entry under the JSON `ignored:` key: what the user already suppressed.
     def ignored_json(result)
       m = result.mutation
       file = result.subject.file
@@ -329,7 +328,7 @@ module Mutineer
     # mutation's 1-based start line, the full original line-block it touches, the
     # spliced mutated block, and a single-line token label for the header.
     def diff_for(m, source)
-      # Byte math (C1): Prism offsets are byte offsets; byteindex/byterindex/
+      # Byte math: Prism offsets are byte offsets; byteindex/byterindex/
       # byteslice keep line splicing correct for multibyte sources.
       line_begin = m.start_offset.zero? ? 0 : (source.byterindex("\n", m.start_offset - 1) || -1) + 1
       line_end   = source.byteindex("\n", m.end_offset) || source.bytesize
@@ -370,9 +369,9 @@ module Mutineer
       out.puts format("Survived:     %-6d  No coverage:   %d", @agg.survived_count, @agg.no_coverage_count)
       out.puts format("Skipped:      %-6d  Errored:       %d", @agg.skipped_invalid_count,
                       @agg.errored_count + @agg.timeout_count)
-      # #9: a broken harness, not a coverage gap — report it distinctly from No coverage.
+      # A broken harness, not a coverage gap: report it distinctly from No coverage.
       out.puts format("Uncapturable: %-6d  (tests failed to run)", @agg.uncapturable_count)
-      # #10: equivalent mutants the user suppressed; excluded from the denominator.
+      # Equivalent mutants the user suppressed; excluded from the denominator.
       out.puts format("Ignored:      %-6d  (equivalent, suppressed)", @agg.ignored_count)
     end
 
@@ -421,10 +420,9 @@ module Mutineer
       parts.join(", ")
     end
 
-    # #11: one line per source after the global summary, so a multi-source run
-    # shows which file is weak. Omitted for a single-source run — the global
-    # summary already says everything (ponytail: no redundant one-line block).
-    # Writes the per-source breakdown.
+    # One line per source after the global summary, so a multi-source run shows
+    # which file is weak. Omitted for a single-source run: the global summary
+    # already says everything (no redundant one-line block).
     #
     # @param out [IO] output stream.
     # @return [void]
@@ -443,7 +441,7 @@ module Mutineer
       end
     end
 
-    # #13: the --baseline delta, appended after the normal report. Names every NEW
+    # The --baseline delta, appended after the normal report. Names every NEW
     # survivor (subject (file:line) operator) and the score delta when it dropped,
     # then a one-line REGRESSION/OK verdict so CI logs show which gate fired.
     def baseline_section(out, delta)

data/lib/mutineer/result.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
 module Mutineer
-  # Immutable outcome of running one mutant. Seven distinct states:
-  #   killed       — a test failed/errored, so the mutation was caught.
-  #   survived     — every test passed, so the mutation went undetected.
-  #   error        — the child crashed (unhandled exception): exit status 2.
-  #   timeout      — the parent SIGKILLed a child that overran its wall clock.
-  #   skipped      — the mutated source failed to re-parse (invalid); no fork.
-  #   no_coverage  — no test exercises the mutated line; not run, not scored.
-  #   uncapturable — the line's would-be covering test errored during capture
-  #                  (#9), so coverage was lost. Excluded from the
-  #                  denominator exactly like no_coverage, but reported
-  #                  separately: it signals a broken harness (a test that
-  #                  failed to run), not a genuine coverage gap.
-  #   ignored      — a known-equivalent mutant the user suppressed (#10), via
-  #                  an inline `# mutineer:disable-line` comment or a
+  # Immutable outcome of running one mutant. Eight distinct states:
+  #   killed       - a test failed/errored, so the mutation was caught.
+  #   survived     - every test passed, so the mutation went undetected.
+  #   error        - the child crashed (unhandled exception): exit status 2.
+  #   timeout      - the parent SIGKILLed a child that overran its wall clock.
+  #   skipped      - the mutated source failed to re-parse (invalid); no fork.
+  #   no_coverage  - no test exercises the mutated line; not run, not scored.
+  #   uncapturable - the line's would-be covering test errored during capture,
+  #                  so coverage was lost. Excluded from the denominator exactly
+  #                  like no_coverage, but reported separately: it signals a
+  #                  broken harness (a test that failed to run), not a genuine
+  #                  coverage gap.
+  #   ignored      - a known-equivalent mutant the user suppressed, via an
+  #                  inline `# mutineer:disable-line` comment or a
   #                  `.mutineer.yml` `ignore:` id. A pre-fork classification
   #                  (never run); excluded from the denominator so a strong
   #                  file can reach 100%.
@@ -22,14 +22,14 @@ module Mutineer
   # `error` and `skipped` are deliberately distinct: skipped is a pre-fork
   # validity failure (counted separately by the reporter), error is a runtime
   # crash. Never conflate them via `details` string parsing. `no_coverage` and
-  # `uncapturable` are pre-fork selection results (M3/#9): both excluded from
-  # the score denominator.
+  # `uncapturable` are pre-fork selection results: both excluded from the score
+  # denominator.
   #
   # `subject`, `mutation`, and `id` are nil when the Result is built by
   # Isolation/Runner (which only know the outcome); the orchestrator attaches
   # them afterwards via `result.with(subject:, mutation:, id:)` so the Reporter
   # can render survivor diffs and emit the stable id. `id` is the content-based
-  # MutantId (#10).
+  # MutantId.
   Result = Data.define(:status, :details, :subject, :mutation, :id) do
     # Builds a killed result.
     #
@@ -93,12 +93,12 @@ module Mutineer
   end
 
   # Aggregates a flat list of Results into counts, the mutation score, and the
-  # surviving-mutant list. The score denominator is killed + survived ONLY
-  # (KTD-4): no-coverage, uncapturable, skipped (invalid), errored, timeout,
-  # and ignored (#10 equivalent-mutant suppression) are each excluded and
-  # surfaced separately — so suppressing every survivor reaches 100%. An empty
-  # denominator yields a nil score (rendered "N/A"), never 0.0 —
-  # distinguishing "no testable mutants" from "0% killed".
+  # surviving-mutant list. The score denominator is killed + survived ONLY:
+  # no-coverage, uncapturable, skipped (invalid), errored, timeout, and ignored
+  # (equivalent-mutant suppression) are each excluded and surfaced separately,
+  # so suppressing every survivor reaches 100%. An empty denominator yields a
+  # nil score (rendered "N/A"), never 0.0, distinguishing "no testable mutants"
+  # from "0% killed".
   class AggregateResult
     attr_reader :results
 
@@ -151,9 +151,8 @@ module Mutineer
     # @return [Array<Mutineer::Result>] surviving results.
     def surviving_mutants = @results.select(&:survived?)
 
-    # #11: split into { source_file => AggregateResult } so the Reporter
-    # (per-source breakdown) and #13 (per-source roll-up / baseline diff) can
-    # reuse the same aggregate math.
+    # Groups results by source file so the Reporter (per-source breakdown) and
+    # baseline diff can reuse the same aggregate math.
     #
     # @return [Hash<String, Mutineer::AggregateResult>] source-file groups.
     def by_source