mutineer 1.3.0 → 1.5.0

data/README.md

@@ -9,12 +9,19 @@ change at a time, runs your test suite (Minitest or RSpec) against each mutant,
 ones your tests failed to catch — the gaps where your suite isn't actually
 testing anything.
 
+"Clean-room" means Mutineer was written from scratch. It contains no code from
+[Mutant](https://github.com/mbj/mutant) or any other mutation-testing tool.
+Mutineer's own code is licensed under MIT. See
+[Mutineer and Mutant](https://github.com/davidteren/mutineer#mutineer-and-mutant)
+for how the two tools differ.
+
 - **Prism + stdlib only** — zero runtime dependencies (Ruby ≥ 3.4).
 - **One mutation per mutant**, validity-checked by re-parsing.
 - **Fork-isolated**, parallel execution (Linux + macOS).
 - **Coverage-guided** — each mutant runs only the test files that cover its line.
 - **Stops at the first failing test** — in-process runs (not `--daemon` or
-  `--test-command`) stop a mutant's test run at the first failure.
+  `--test-command`) stop a mutant's test run at the first failure, unless
+  `--matrix` asks for every covering test.
 
 📖 **[mutineer.github.io →](https://davidteren.github.io/mutineer/)** — overview, operators, and usage.
 
@@ -33,7 +40,7 @@ gem "mutineer", group: :test
 ## Usage
 
 ```sh
-mutineer run <source...> --test <test...> [options]
+mutineer run <source...> --test <test> [--test <test>...] [options]
 ```
 
 Mutate `lib/calculator.rb`, checking it against its test, and fail CI if the
@@ -47,24 +54,30 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 
 | Flag | Meaning |
 |------|---------|
-| `--test FILE` | Test file covering the sources (repeatable) |
+| `--test FILE` | Test file covering the sources; one file per flag, so repeat it for each (`--test a_test.rb --test b_test.rb`) |
 | `--operators LIST` | Comma-separated operator names (default: the Tier-1 set) |
 | `--threshold FLOAT` | Exit 1 when the score is below FLOAT, or when nothing could be scored and something broke, or more than one mutant produced no verdict and they exceed 10% of those attempted (default: 0 = off) |
 | `--only NAME` | Restrict to one fully-qualified subject, e.g. `Calculator#add` |
 | `--framework NAME` | `minitest` (default) or `rspec`; auto-detected as rspec when most `--test` files end in `_spec.rb` |
-| `--since REF` | Only mutate lines changed since git `REF` (e.g. `origin/main`) — ideal for PR CI |
+| `--since REF` | Only mutate lines changed since git `REF` (e.g. `origin/main`). Untracked files are scored in full unless Git ignores them. |
 | `--no-since` | Disable diff scoping; a typed no beats a `.mutineer.yml` `since:` key |
-| `--baseline FILE` | Compare against a prior `--format json` run; exit 1 on new survivors / score drop (score drop is skipped under `--since`, whose score covers a different denominator; see [CI](#ci-gating)) |
+| `--baseline FILE` | Compare against a prior `--format json` run; exit 1 on new survivors / score drop (score drop is skipped under `--since`, whose score covers a different denominator; see [CI](https://github.com/davidteren/mutineer#ci-gating)) |
 | `--baseline-epsilon FLOAT` | Score-drop tolerance for `--baseline` (default: 0) |
-| `--jobs N` | Parallel worker count (default: processor count; `1` under `--rails`) |
+| `--jobs N` | Parallel worker count (default: processor count); forced to `1` by `--test-command`, `--fail-fast`, or `--rails` without `--daemon` |
+| `--boot FILE` | Require an app entry point once before forking; select at least one test file |
+| `--rails` | Boot `config/environment` and reconnect ActiveRecord per fork; without `--daemon`, defaults to `redefine` and runs serially |
 | `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
-| `--test-command CMD` | Run the suite as a subprocess in the app's own runtime (for apps on Ruby < 3.4); `CMD` must contain `%{files}`. See [Apps on Ruby < 3.4](#apps-on-ruby--34) |
-| `--daemon` | Boot the app once in a persistent daemon and fork per mutant, with per-worker DB isolation so `--jobs N` is safe under Rails (needs `--rails`/`--boot`; not with `--test-command`). See [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend) |
+| `--timeout SECONDS` | Per-mutant time limit for in-process runs, in whole seconds (default: 10). A mutant whose tests run longer is a `timeout`; see [Timeouts and the score](https://github.com/davidteren/mutineer#timeouts-and-the-score). `--daemon` and `--test-command` keep their own limits |
+| `--capture-timeout SECONDS` | Time limit for each in-process coverage-capture subprocess and for the clean run of the unmutated tests, in whole seconds (default: 120). A suite slower than this stops the run as not green. `--daemon` uses it for its coverage capture; `--test-command` ignores it and says so |
+| `--cache-dir DIR` | Directory for the coverage cache (default: `.mutineer`). Give two runs from the same project root different directories so they do not share `coverage.json`. `--test-command` builds no cache, so it ignores it and says so |
+| `--test-command CMD` | Run the suite as a subprocess in the app's own runtime (for apps on Ruby < 3.4); `CMD` must contain `%{files}`. See [Apps on Ruby < 3.4](https://github.com/davidteren/mutineer#apps-on-ruby--34) |
+| `--daemon` | Boot the app once in a persistent daemon and fork per mutant, with per-worker DB isolation so `--jobs N` is safe under Rails (needs `--rails`/`--boot`; not with `--test-command`). See [the daemon backend](https://github.com/davidteren/mutineer#faster-parallel-safe-rails-the---daemon-backend) |
 | `--format human\|json\|html` | Report format (default: human; `html` is a self-contained file) |
 | `--output FILE` | Write the report to FILE instead of stdout |
 | `--dry-run` | List candidate mutations without executing (honors suppression) |
-| `--fail-fast` | Stop at the first surviving mutant |
+| `--fail-fast` | Stop at the first surviving mutant (`--no-fail-fast` beats a `.mutineer.yml` `fail_fast:` key) |
+| `--matrix` | Run every covering test for each mutant and report the blind and redundant tests; the JSON report also lists each mutant's killers. In-process only; exits 2 with `--daemon`, `--test-command`, `--fail-fast` or `--dry-run`. RSpec needs 3.3 or later. `--no-matrix` beats a `.mutineer.yml` `matrix:` key. See [Kill matrix](https://github.com/davidteren/mutineer#kill-matrix) |
 | `--list-operators` | List available operators (default vs optional) and exit |
 | `--version`, `--help` | Print version / usage and exit |
 
@@ -85,7 +98,8 @@ Run `mutineer --list-operators` to see them. Default (Tier 1): `arithmetic`,
 Available but off by default (Tier 2, enable via `--operators`): `return_nil`,
 `literal_mutation`, `condition_negation`, `string_literal`, `regex`,
 `collection_method`, `safe_navigation`, `range`, `negation_removal`, `chain_link`,
-`operand_removal`, `array_literal`.
+`operand_removal`, `array_literal`, `condition_true`,
+`condition_false`, `operator_assignment`.
 
 ## Rails apps
 
@@ -98,8 +112,8 @@ RAILS_ENV=test bundle exec mutineer run \
 ```
 
 `--rails` boots `config/environment` once in the parent process (every mutant
-then forks and inherits it), defaults `--strategy` to `redefine` (surgical — it
-avoids reloading files into the app tree), and reconnects ActiveRecord in each
+then forks and inherits it), defaults `--strategy` to `redefine` without `--daemon`
+(surgical — it avoids reloading files into the app tree; `--daemon` keeps `reload`), and reconnects ActiveRecord in each
 fork so the database connection is fork-safe. Use `--boot FILE` to boot a
 different entry point. Boot mode requires at least one `--test` file and is
 coverage-guided — each mutant runs only the test files that exercise its line
@@ -134,9 +148,10 @@ RAILS_ENV=test bundle exec mutineer run \
 - **One backend at a time** — `--daemon` can't be combined with `--test-command`
   (choose one), and it needs an app to boot (`--rails` or `--boot`).
 
-Status: **SQLite** today (hermetic, CI-proven). **Postgres** per-worker
-provisioning is in progress (#34/#35); until it lands, use `--daemon` with a
-SQLite test database, or drop `--jobs` to run serially on other adapters.
+Status: **SQLite** only (hermetic, CI-proven). Per-worker provisioning for
+**Postgres** and other adapters is not supported: on those, `--daemon` scores
+every mutant as `error`. Use `--daemon` with a SQLite test database, or drop
+`--daemon` to run serially on other adapters.
 
 ### Apps on Ruby < 3.4
 
@@ -206,7 +221,23 @@ Tradeoffs — this path is correct but not free:
   front (a "smoke check") if your unmutated suite isn't green.
 - **Reload strategy only** (`--strategy redefine` is rejected on this path) and
   **serial** (`--jobs` is forced to 1). For apps on Ruby ≥ 3.4, `--daemon` gives
-  safe parallelism instead (see [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend)).
+  safe parallelism instead (see [the daemon backend](https://github.com/davidteren/mutineer#faster-parallel-safe-rails-the---daemon-backend)).
+
+## Timeouts and the score
+
+The mutation score is `killed / (killed + survived)`. A mutant whose tests run
+past `--timeout` is a `timeout`. It is neither killed nor survived, so it is
+left out of the score, like `no_coverage`, `uncapturable`, `errored`, skipped
+and ignored mutants. A timeout is not counted as a kill, because a hang the
+mutant caused and a suite that is just slow look the same. The human report
+shows the count in its `Timeout:` row, and the JSON report in `summary.timeout`.
+
+Under `--threshold`, a timeout is a mutant with no verdict. The run exits 1 when
+more than one mutant produced no verdict and they exceed 10% of those attempted,
+or when nothing could be scored and something broke. If a slow suite times out
+mutants that its tests would catch, raise `--timeout`. A limit set below what
+the suite needs does not raise the score: it turns those mutants into timeouts,
+and once they pass 10% of the attempted mutants the run fails.
 
 ## Suppressing equivalent mutants
 
@@ -267,6 +298,77 @@ Ids are relative to the directory you run mutineer from. mutineer finds
 (other than your home directory), it warns that the ignore ids will not match
 and tells you which directory to run from.
 
+## Kill matrix
+
+`--matrix` reports which tests kill each mutant, and from that, which tests
+add nothing to the suite.
+
+```sh
+mutineer run lib/calculator.rb --test test/calculator_test.rb --matrix
+```
+
+For each mutant, Mutineer runs every test in its covering files instead of
+stopping at the first failure, and records which tests failed. Coverage is
+recorded per test file, so that set also holds tests that never reach the
+mutated line; they pass and count as having run. A mutant's row is complete
+when its whole covering set ran and the suite returned normally (under
+Minitest, an `Interrupt` that cut the run short does not count as returning
+normally). The report
+names two kinds of test:
+
+- **Blind:** the test ran in at least one complete row and killed no mutant
+  in any row. It would still pass with this run's mutations of the code, so
+  it guards none of them. It can still check behavior outside this run's
+  mutants (code in other files, or edits no operator makes), so look at what
+  it asserts before you delete it, or give it an assertion that can fail.
+- **Redundant:** every mutant the test kills, another test kills too. That
+  makes it a candidate for deletion, one test at a time: two redundant tests
+  can be the only killers of one mutant, so re-run after each deletion.
+
+The answers cover this run's mutants only. A test of code outside the sources
+you passed kills nothing here, so mutate the code a test exercises before you
+call the test blind.
+
+The matrix changes no verdict, score or exit code: each mutant gets the
+verdict a run without `--matrix` gives. That run skips every later test,
+test class and example group after the first failure, so when a later one
+exits the process, crashes or runs into the time limit, the mutant is still
+`killed`. The run without `--matrix` still runs the code around the failing
+test (the rest of its Minitest class `run` wrapper, the `after(:all)` hooks of
+its RSpec groups) and the suite's own cleanup (RSpec's `after(:suite)`), so an
+end there keeps the exit status. A failure in a Minitest `parallelize_me!`
+class also keeps it: those run after every serial class and cannot be stopped
+once queued, while a failure in a serial class still stops the run.
+
+Under RSpec, `--matrix` needs RSpec 3.3 or later, whose example ids tell
+apart examples on one line. With an older RSpec every row is incomplete.
+
+The human report lists up to 20 blind and 20 redundant tests, and the HTML
+report lists them all. `--format json` adds a `matrix` block with every test
+and each mutant's killers (see the
+[JSON schema](https://davidteren.github.io/mutineer/json-schema.html#matrix)).
+A test is its file and its id. The name is `CalculatorTest#test_add` under
+Minitest, or the example's full description under RSpec, where the example id
+(`./spec/calc_spec.rb[1:2]`) tells apart examples that share a description
+and keeps an example whose generated description changes with the mutant as
+one test.
+
+Each mutant runs its whole covering set, so every mutant costs what a survivor
+costs. In 1.4, stopping at the first failure cut a full run of rack's
+`lib/rack/utils.rb` from 86 to 89 seconds down to 35 to 41, so expect a matrix
+run to take 2.1 to 2.5 times as long as a normal one. A mutant that reaches the
+per-mutant time limit (`--timeout`, 10 seconds by default) after a test already failed stays `killed`
+with its row marked incomplete. The report names each incomplete row and warns
+that a blind test may have killed one of those mutants, so do not delete a
+blind test until its rows are complete. Raise `--timeout` (or `timeout:` in
+`.mutineer.yml`) to get complete rows.
+
+`--matrix` runs on the in-process backend only. It exits 2 with `--daemon`,
+`--test-command`, `--fail-fast` or `--dry-run`, and the message says whether
+each setting came from the command line or `.mutineer.yml`. To run one of
+those with `matrix: true` in the file, pass `--no-matrix`; to run `--matrix`
+with `fail_fast: true` in the file, pass `--no-fail-fast`.
+
 ## CI gating
 
 Store a JSON run as a baseline, then fail the build only when a PR makes things
@@ -276,10 +378,15 @@ worse:
 mutineer run app/ --baseline .mutineer/baseline.json   # exit 1 on NEW survivors or a score drop
 ```
 
-`--baseline` reports which survivors are new (by [mutant id](#mutant-ids)) and any score drop. It
+`--baseline` reports which survivors are new (by [mutant id](https://github.com/davidteren/mutineer#mutant-ids)) and any score drop. It
 combines with `--threshold` (the worse of the two sets the exit code). Pass a
 directory (or several sources) to audit a whole layer in one boot — tests are
-auto-paired by convention and the report breaks down per source.
+auto-paired by convention and the report breaks down per source. A source
+`app/foo/bar.rb` pairs with `test/foo/bar_test.rb` and with unclaimed
+`test/foo/bar_*_test.rb` files in that directory, such as `bar_upsert_test.rb`.
+It does not take `user_session_test.rb` when `user_session.rb` exists in the same directory.
+It does not take `bar_upsert_guards_test.rb` when `bar_upsert.rb` exists.
+A spec that already pairs is left as that one file.
 
 ### GitHub Action
 
@@ -315,17 +422,17 @@ the format.
 
 ## For AI agents & pipelines
 
-Mutineer is built for programmatic use — versioned JSON, [mutant ids](#mutant-ids) that survive unrelated edits,
+Mutineer is built for programmatic use — versioned JSON, [mutant ids](https://github.com/davidteren/mutineer#mutant-ids) that survive unrelated edits,
 structured exit codes, and diff-scoped runs. See:
 
 - **AI agents & CI recipes** — the agent inner-loop and CI-gate recipes (and how
   to avoid infinite loops on equivalent mutants):
   [rendered](https://davidteren.github.io/mutineer/agentic-coding.html) ·
-  [source](docs/agentic-coding.md)
+  [source](https://davidteren.github.io/mutineer/agentic-coding.md)
 - **JSON schema reference** — the `--format json` schema and its versioning
   contract:
   [rendered](https://davidteren.github.io/mutineer/json-schema.html) ·
-  [source](docs/json-schema.md)
+  [source](https://davidteren.github.io/mutineer/json-schema.md)
 - **Ruby API (YARD)** — class reference for the shipped gem:
   [https://davidteren.github.io/mutineer/api/](https://davidteren.github.io/mutineer/api/)
 
@@ -334,11 +441,44 @@ structured exit codes, and diff-scoped runs. See:
 Mutineer reads an optional `.mutineer.yml` from the project root (nearest one,
 walking up). CLI flags override config; config overrides defaults.
 
-Sources are positional CLI arguments and test files come from `--test`; the
-config file accepts these keys: `operators`, `threshold`, `jobs`, `only`,
-`require` (extra files to load before mutating), `boot`/`rails`, and
-`test_command` (the external-runtime suite command — see
-[Apps on Ruby < 3.4](#apps-on-ruby--34)).
+Sources are positional CLI arguments and test files come from `--test`. The
+config file accepts these keys:
+
+| Key | Value and purpose |
+|-----|-------------------|
+| `operators` | An operator name or list of names; defaults to the Tier-1 set |
+| `threshold` | A number from 0 to 100; 0 turns the score gate off |
+| `jobs` | A positive integer; the default is the processor count. `test_command`, `fail_fast`, or `--rails` without `--daemon` forces 1. |
+| `only` | A fully-qualified subject name, such as `Calculator#add` |
+| `require` | A path or list of extra files to load before mutating |
+| `boot` | The app entry point to require once before forking |
+| `rails` | `true` or `false`; enables the Rails boot defaults |
+| `since` | A nonblank git ref, or `false` to disable diff scoping |
+| `framework` | `minitest` or `rspec`; an explicit value is kept during test pairing |
+| `verbose` | `true` or `false`; shows capture diagnostics |
+| `ignore` | A mutant id or list of ids to suppress |
+| `baseline` | The path to a prior JSON report |
+| `fail_fast` | `true` or `false`; stops scheduling after the first survivor |
+| `test_command` | The external-runtime suite command, including `%{files}`; see [Apps on Ruby < 3.4](https://github.com/davidteren/mutineer#apps-on-ruby--34) |
+| `daemon` | `true` or `false`; uses the persistent app daemon with worker DB isolation |
+| `timeout` | A positive integer; the per-mutant time limit in seconds (default 10) |
+| `capture_timeout` | A positive integer; the coverage-capture time limit in seconds (default 120) |
+| `cache_dir` | The coverage cache directory (default `.mutineer`) |
+| `matrix` | `true` or `false`; runs every covering test for each mutant and adds the kill matrix to the report |
+
+Invalid values for known scalar keys, and a blank `operators` list, exit 2
+with a message naming the file and key. An unknown operator name warns and
+is skipped. If none of the names are known, the run exits 2. An empty
+`require` or `ignore` list is valid. Boolean keys take `true` or `false` (quoted forms also work), not `"yes"`.
+`jobs` must be positive; a string value contains digits only. String values for
+`threshold` and the CLI-only `--baseline-epsilon` use plain decimals such as `90`
+or `0.5`, not `+2`, `1e2`, or `1_0`. String options such as `only` and `baseline`
+cannot be null or boolean. A blank `since` is invalid; use `since: false` to turn
+scoping off. Unknown keys warn and are ignored. Unknown operator names warn and are skipped, and the run exits 2 when none remain. `--operators` replaces a blank or unknown file list.
+
+`format`, `strategy`, `output`, `baseline_epsilon`, and `dry_run` are CLI-only.
+For JSON output, use `--format json`, not a `format:` config key. To select RSpec
+in the file, add `framework: rspec`.
 
 ```yaml
 # .mutineer.yml
@@ -350,8 +490,40 @@ require:
 ```
 
 Coverage results are cached in `.mutineer/coverage.json` (digest-keyed; rebuilt
-automatically when sources change). Add `.mutineer/` to your `.gitignore`.
+automatically when sources change). Add `.mutineer/` to your `.gitignore`, and
+the directory you set with `--cache-dir` if it is inside the project. Keep
+`.mutineer/` ignored even then: `--test-command` writes lock files to
+`.mutineer/` beside each source file.
+
+## Mutineer and Mutant
+
+[Mutant](https://github.com/mbj/mutant), by Markus Schirp, is the established
+mutation-testing tool for Ruby. It has been in development since 2012 and is
+the subject of published research. Mutineer is a separate tool, and it shares
+no code with Mutant.
+
+| Aspect | Mutineer | Mutant |
+|---|---|---|
+| License | MIT, for every use | Free for open source (`--usage opensource`); commercial use needs a paid subscription |
+| Runtime dependencies | None (Prism + stdlib) | `parser`, `unparser`, `regexp_parser`, `sorbet-runtime` and others |
+| Ruby | 3.4 and later to run Mutineer; an app on an older Ruby works through `--test-command` (see [Apps on Ruby < 3.4](https://github.com/davidteren/mutineer#apps-on-ruby--34)) | 3.3 and later |
+| Test frameworks | Minitest and RSpec, in one gem | RSpec, Minitest and Test::Unit, one integration gem each |
+| What you mutate | Files (`mutineer run lib/foo.rb --test test/foo_test.rb`), narrowed to one method with `--only 'Foo#bar'` | Subjects named by expression (`mutant run 'Foo#bar'`, `'Foo*'`) |
+| Which tests run | The test files whose coverage reaches the mutated line | The tests that declare the subject (an RSpec description or a Minitest `cover`), or the tests that ran it in a per-test coverage recording |
+| Operators | 20 (5 by default, 15 opt-in) | A larger set; the default `light` set applies almost all of it (`full` adds `#==` to `#eql?`) |
+| CI gating | `--threshold`, `--baseline` deltas, `--since`, and a GitHub Action | Incremental mode (`--since`) and a recorded session history |
+| Machine-readable output | Versioned JSON report schema | Session JSON schema |
+
+Choose Mutineer when you want an MIT-licensed tool with no extra gems in your
+bundle, file-based runs, and a JSON contract built for CI gates and AI agents.
+Choose Mutant when you need its deeper operator set, Test::Unit support, or
+subject expressions that select whole namespaces. The two tools do not
+conflict, so you can run both on one project.
+
+This comparison describes Mutant 0.17 (checked on 2026-10-06). Check
+[Mutant's README](https://github.com/mbj/mutant#readme) for its current
+license terms and features.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/davidteren/mutineer/blob/main/LICENSE).

data/lib/mutineer/changed_lines.rb

@@ -56,6 +56,12 @@ module Mutineer
     end
 
     # Returns the stdout of `git -C <root> diff --unified=0 <ref> -- <file>`.
+    # A file that is not in the index has no usable diff, so `new_file_diff`
+    # supplies one that marks every line new. That includes a file the ref still
+    # has, deleted and then written again: git prints only a deletion hunk for it.
+    # A Git-ignored file outside the index contributes no changed lines, with a
+    # warning, so the skip does not look like a file with no changes.
+    # Paths are literal, so a name such as `file[1].rb` is not read as a glob.
     #
     # A failure is warned, never silent: an empty result means "no changed
     # lines", which under `--since` removes every mutant for the file — a green
@@ -67,9 +73,15 @@ module Mutineer
     # @return [String] diff text, or `""` on failure (after a stderr warning).
     def git_diff(ref, abs_file, project_root)
       out, _err, status = Open3.capture3(
-        "git", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file
+        "git", "--literal-pathspecs", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file
       )
-      return out if status.success?
+      if status.success?
+        return out if indexed?(abs_file, project_root)
+        return new_file_diff(abs_file) unless ignored?(abs_file, project_root)
+
+        warn "[mutineer] #{abs_file} is ignored by Git; its lines will not be mutated (--since)"
+        return ""
+      end
 
       warn "[mutineer] git diff failed for #{abs_file}; its lines will not be mutated (--since)"
       ""
@@ -77,5 +89,48 @@ module Mutineer
       warn "[mutineer] git diff failed for #{abs_file} (#{e.class}); its lines will not be mutated (--since)"
       ""
     end
+
+    # Tells whether the index holds the file. Only then is git's own diff the
+    # truth; the diff text cannot tell, because a mode-only diff must stay empty.
+    #
+    # @param abs_file [String] absolute path of the file being diffed.
+    # @param project_root [String] repository root for `git -C`.
+    # @return [Boolean] true when the index holds the file.
+    def indexed?(abs_file, project_root)
+      _out, _err, known = Open3.capture3(
+        "git", "--literal-pathspecs", "-C", project_root, "ls-files", "--error-unmatch", "--", abs_file
+      )
+      known.success?
+    end
+
+    # Tells whether Git ignores the file (`.gitignore`, `.git/info/exclude` or
+    # the global excludes file).
+    #
+    # @param abs_file [String] absolute path of the file.
+    # @param project_root [String] repository root for `git -C`.
+    # @return [Boolean] true when Git ignores the file. False when Git cannot
+    #   tell, such as for a path beyond a symlink or inside a submodule (exit
+    #   128): that file is scored in full, as a file Git does not ignore is.
+    def ignored?(abs_file, project_root)
+      _out, _err, status = Open3.capture3(
+        "git", "-C", project_root, "check-ignore", "--quiet", "--", abs_file
+      )
+      status.success?
+    end
+
+    # Returns a diff that marks a file as entirely new. It returns `""` when
+    # the file is empty or cannot be read (after a warning). A file outside the
+    # index has every line new; read as "unchanged", `--since` would score
+    # nothing and a positive threshold would still exit 0.
+    #
+    # @param abs_file [String] absolute path of the file being diffed.
+    # @return [String] a one-hunk diff header, or `""`.
+    def new_file_diff(abs_file)
+      count = File.foreach(abs_file).count
+      count.zero? ? "" : "@@ -0,0 +1,#{count} @@\n"
+    rescue SystemCallError => e
+      warn "[mutineer] cannot read #{abs_file} (#{e.class}); its lines will not be mutated (--since)"
+      ""
+    end
   end
 end