hecks 4.0.0 → 6.0.0

data/lib/hecks/projector/narrate_projector.rb

@@ -10,9 +10,9 @@ module Hecks
 
       # Projects `bluebook` as prose; `options[:heading]` sets the top heading level.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook to narrate
       # @param options [Hash] `:heading` (Integer, default 1) and `:aggregate` (narrows to one
-      #   aggregate, omitting the chapter intro and reactions)
+      #   aggregate, omitting the bluebook intro and reactions)
       # @return [String] Markdown prose ending in a newline
       # @raise [Runtime::NotFound] if `options[:aggregate]` names no declared aggregate
       def call(bluebook:, options: {})
@@ -20,7 +20,7 @@ module Hecks
         only  = options[:aggregate]
 
         sections = []
-        sections << chapter_intro(bluebook, depth) unless only
+        sections << bluebook_intro(bluebook, depth) unless only
         sections.concat(aggregate_narratives(bluebook, only, only ? depth : depth + 1))
         sections << Reactions.narrative(bluebook, depth + 1) unless only
         "#{sections.compact.join("\n\n").rstrip}\n"
@@ -31,15 +31,16 @@ module Hecks
         Array(DocsProjector.aggregates(bluebook, only)).map { |aggregate| aggregate_narrative(aggregate, depth) }
       end
 
-      def chapter_intro(bluebook, depth)
+      def bluebook_intro(bluebook, depth)
         names = bluebook.aggregates.map(&:hecks_name)
-        parts = [DocsProjector.h(depth, bluebook.name), bluebook.vision, chapter_meta(bluebook)]
+        parts = [DocsProjector.h(depth, bluebook.name), bluebook.vision, bluebook_meta(bluebook)]
         parts << "It's told through #{to_sentence_list(names)}." unless names.empty?
         parts.compact.join("\n\n")
       end
 
-      # The chapter's classification and former name as one paragraph, or `nil` when it has neither.
-      def chapter_meta(bluebook)
+      # The bluebook's classification and former name as one paragraph, or `nil` when it has
+      # neither.
+      def bluebook_meta(bluebook)
         meta = []
         meta << "This is a #{bluebook.classification} domain." if bluebook.classification
         meta << "It was formerly known as `#{bluebook.formerly_known_as}`." if bluebook.formerly_known_as
@@ -63,7 +64,7 @@ module Hecks
         refs = aggregate.attributes.select(&:reference?)
         return nil if refs.empty?
 
-        targets = refs.map { |r| "#{a_or_an(r.type.target_name)} #{r.type.target_name}" }
+        targets = refs.map { |r| "#{a_or_an(r.target_name)} #{r.target_name}" }
         "Each one is linked to #{to_sentence_list(targets)}."
       end
 

data/lib/hecks/projector/target.rb

@@ -17,8 +17,8 @@ module Hecks
       #
       # @param key [String, Symbol] key to register `self` under
       # @param requires [Module, Array<Module>, nil] capability module(s) required;
-      #   nil/empty means `Bluebook::Behaviour::Chapter`
-      # @param declares [String, Symbol, Array, nil] aggregate name(s) the chapter must declare
+      #   nil/empty means `Bluebook::Behaviour::Bluebook`
+      # @param declares [String, Symbol, Array, nil] aggregate name(s) the bluebook must declare
       # @param emits [Symbol] :artifact (a Hash/String, the default) or :files (a path => tree)
       # @param needs_world [Boolean] true refuses a call made with no `world:` bindings
       # @return [Symbol] the registered key
@@ -37,11 +37,11 @@ module Hecks
       # @return [Symbol, nil] the key given to `projects_as`, or nil before it is called
       def projection_key = @projection_key
 
-      # Empty means "a chapter" — resolved here rather than as a default
-      # argument, because Behaviour::Chapter is not loaded yet when this
+      # Empty means "a bluebook" — resolved here rather than as a default
+      # argument, because Behaviour::Bluebook is not loaded yet when this
       # file is.
       #
-      # @return [Array<String, Symbol>] aggregate names the chapter must declare; empty
+      # @return [Array<String, Symbol>] aggregate names the bluebook must declare; empty
       #   for none
       def projection_declares = @projection_declares || []
 
@@ -62,7 +62,7 @@ module Hecks
       # so there is no second spelling to drift.
       #
       # @return [Symbol] `:export` if it needs a world, `:meta` if it needs a
-      #   chapter declaring particular aggregates, otherwise `:projection`
+      #   bluebook declaring particular aggregates, otherwise `:projection`
       def projection_category
         return :export if projection_needs_world?
 
@@ -70,12 +70,12 @@ module Hecks
       end
 
       # Names the capability module(s) a construct must satisfy, defaulting
-      # to plain chapter-hood when `projects_as` named none.
+      # to plain bluebook-hood when `projects_as` named none.
       #
       # @return [Array<Module>] required capability modules
       def projection_requires
         req = @projection_requires
-        req.nil? || req.empty? ? [Bluebook::Behaviour::Chapter] : req
+        req.nil? || req.empty? ? [Bluebook::Behaviour::Declaration] : req
       end
     end
   end

data/lib/hecks/projector.rb

@@ -2,18 +2,18 @@ module Hecks
   # A named registry of "canonical IR in, external artifact out" tools, each
   # taking one bluebook's IR and answering a derived artifact (`:ir`, `:docs`, ...).
   #
-  #   Projector.call(:ir, bluebook: chapter)
+  #   Projector.call(:ir, bluebook: bluebook)
   #
   # A target's category is derived from the flags it declares (`category`):
   #
-  # - `:projection` is inert and derived from any chapter's declaration.
-  # - `:meta` also needs a chapter declaring particular aggregates (`declares:`),
-  #   so it only fits hecks's own grammar chapters.
+  # - `:projection` is inert and derived from any bluebook's declaration.
+  # - `:meta` also needs a bluebook declaring particular aggregates (`declares:`),
+  #   so it only fits hecks's own grammar bluebooks.
   # - `:export` (CloudFormation, ...) also needs `.world` bindings and declares
   #   `needs_world: true`; that is adapter wiring, not a projection of the domain.
   module Projector
     class UnknownProjector < StandardError; end
-    # A chapter-scoped projector was handed something that is not a chapter.
+    # A bluebook-scoped projector was handed something that is not a bluebook.
     class WrongConstruct < StandardError; end
 
     module_function
@@ -32,7 +32,7 @@ module Hecks
     # after refusing a construct it does not admit.
     #
     # @param name [String, Symbol] the registered projector's key
-    # @param bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the construct to project
+    # @param bluebook [Bluebook::Behaviour::Bluebook, Hecks::IR] the construct to project
     # @param options [Hash] projector-specific options, passed through unchanged
     # @param world [Bluebook::World, nil] bindings an export needs (`needs_world: true`);
     #   merged into `options[:world]`
@@ -55,7 +55,7 @@ module Hecks
     # @param name [String, Symbol] the projector's registered key, used in the message
     # @param projector [Module, Class, #call] the target; consulted for `projection_requires`,
     #   `projection_declares` and `projection_needs_world?` when it answers them
-    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the construct offered
+    # @param construct [Bluebook::Behaviour::Bluebook, Hecks::IR] the construct offered
     # @param world [Bluebook::World, nil] the `world:` given to `Projector.call`
     # @return [void]
     # @raise [WrongConstruct] if a required capability or aggregate is missing, or the
@@ -86,13 +86,13 @@ module Hecks
       return if absent.empty?
 
       raise WrongConstruct,
-            "#{name.inspect} needs a chapter declaring #{absent.join(" and ")}; " \
+            "#{name.inspect} needs a bluebook declaring #{absent.join(" and ")}; " \
             "#{construct.name} declares no such aggregate."
     end
 
     # Tells whether `construct` has the capability `admits!` requires of it.
     #
-    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the construct to check
+    # @param construct [Bluebook::Behaviour::Bluebook, Hecks::IR] the construct to check
     # @param capability [Module] the capability module to check for
     # @return [Boolean] true if `construct` is a `capability`
     def capable?(construct, capability) = construct.is_a?(capability)

data/lib/hecks/quality_control/adapters/agent.rb

@@ -2,6 +2,7 @@
 
 require "open3"
 require "shellwords"
+require_relative "../../text"
 require_relative "agent_profile"
 
 module Hecks
@@ -53,7 +54,7 @@ module Hecks
         File.open(log, "a") { |file| file.puts(output) } if log
         return output if status.success?
 
-        raise Failed, "agent exited #{status.exitstatus}: #{output.lines.last(5).join.strip}"
+        raise Failed, "agent exited #{status.exitstatus}: #{Text.last_lines(output, 5)}"
       rescue SystemCallError => e
         raise Failed, "agent could not start (#{words.first}): #{e.message}"
       end

data/lib/hecks/quality_control/adapters/github_checks.adapter

@@ -1,4 +1,4 @@
-# Binds the `CI` port to `GithubChecks` for any boot that loads the QualityControl chapter.
+# Binds the `CI` port to `GithubChecks` for any boot that loads the QualityControl bluebook.
 # The implementation is required by name, not relative to this file, because the `.adapter` glob
 # never loads the sibling `.rb` and a copy of this directory (a fuzz boot) must share the one
 # implementation already loaded.

data/lib/hecks/quality_control/adapters/github_issues.adapter

@@ -1,4 +1,4 @@
-# Binds the `IssueTracker` port to `GithubIssues` for any boot that loads the chapter.
+# Binds the `IssueTracker` port to `GithubIssues` for any boot that loads the bluebook.
 # Required by name, not relative, so a copy of this directory shares the one implementation loaded.
 require "hecks/quality_control/adapters/github_issues"
 

data/lib/hecks/quality_control/adapters/github_issues.rb

@@ -11,6 +11,9 @@ module Hecks
       # Raised when `gh` cannot file the issue.
       class Error < RuntimeError; end
 
+      # The end of a GitHub issue URL, capturing the issue's number.
+      ISSUE_NUMBER = %r{/issues/(\d+)\z}
+
       # @param aggregate [Object, nil] unused
       # @param settings [Hash] unused
       # @param root [String, nil] unused
@@ -39,8 +42,9 @@ module Hecks
       end
 
       def issue_url_and_number(out)
-        url = out.strip.lines.last.to_s.strip
-        number = url[%r{/issues/(\d+)\z}, 1]
+        last_line = out.strip.lines.last
+        url = last_line.to_s.strip
+        number = url[ISSUE_NUMBER, 1]
         raise Error, "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
 
         [url, number]

data/lib/hecks/quality_control/adapters/target_tools.rb

@@ -5,9 +5,9 @@ require_relative "qa_tool"
 module Hecks
   module Adapters
     # The `TargetTools` port's adapter: answers `Target`'s queries by running the QA commands that
-    # enrol, generate and judge chapters: the seed, the generated-domain check, the combination
-    # miner, the novelty gate and the external-domain scan. A finding or a judgment is an answer;
-    # anything else the command calls an error is refused with its report.
+    # enrol, generate and judge bluebooks: the seed, the generated-domain check, the combination
+    # miner, the mutation test, the novelty gate and the external-domain scan. A finding or a
+    # judgment is an answer; anything else the command calls an error is refused with its report.
     class TargetTools < QaTool
       # @return [Hash] `text:` each corpus domain's outcome: identified, or already on file
       def seed
@@ -26,6 +26,12 @@ module Hecks
         run_command("qa_mine_combinations", *words(arguments), answers: [0, 1])
       end
 
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--from-dials`
+      # @return [Hash] `text:` the kill rate, and every mutant no test caught
+      def mutate(arguments: nil)
+        run_command("qa_mutate", *words(arguments), answers: [0, 2])
+      end
+
       # @param domain [Hash, String] the candidate stress domain's path
       # @param arguments [Hash, String, nil] `--against` and the paths to compare with
       # @return [Hash] `text:` the new form pairs it earns its place with, or that it earns none

data/lib/hecks/quality_control/cli/child.rb

@@ -16,6 +16,7 @@ module Hecks
         "qa_pr_check"                  => ["QaPrCheck", :argv_root],
         "qa_generated_domains"         => ["QaGeneratedDomains", :argv_root],
         "qa_mine_combinations"         => ["QaMineCombinations", :argv_root],
+        "qa_mutate"                    => ["QaMutate", :argv_root],
         "qa_domain_novelty"            => ["QaDomainNovelty", :argv_root],
         "qa_discover_external_domains" => ["QaDiscoverExternalDomains", :argv_root],
         "qa_concurrency_racer"         => ["QaConcurrencyRacer", :argv_root],

data/lib/hecks/quality_control/cli/qa_domain_novelty/verdict.rb

@@ -9,7 +9,7 @@ module Hecks
         # Why an empty result is a question about the census, not a verdict on the domain.
         READ_AS_QUESTION = "READ THAT AS A QUESTION ABOUT THE CENSUS, NOT A VERDICT ON THE DOMAIN. This gate " \
                            "measures ONE AGGREGATE's own declared forms, so a domain whose point is a " \
-                           "chapter-level construct — a policy, an `across` target, a process manager, a " \
+                           "bluebook-level construct — a policy, an `across` target, a process manager, a " \
                            "read model's own group_by/median, an outbox, a dry run — is invisible to it by " \
                            "construction, not by omission. `corrects` and `role_gated` were exactly that: " \
                            "declared all over the corpus, unnamed here, so this line told three stress " \

data/lib/hecks/quality_control/cli/qa_generated_domains/evaluation.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../../../text"
 
 module Hecks
   module QualityControlCli
@@ -8,6 +9,9 @@ module Hecks
       # Checking one candidate domain: written to disk, optionally built against Rust, then run in
       # its own child process.
       module Evaluation
+        # A compiler output line that reports an error.
+        COMPILER_ERROR = /error/
+
         private
 
         # `--check DIR`: one domain in this process, one result line.
@@ -43,7 +47,7 @@ module Hecks
           return JSON.parse(line.delete_prefix(RESULT_MARKER)) if line
 
           { "status" => "error",
-            "error"  => "child exited #{status.exitstatus} with no result: #{output.lines.last(5).join.strip}" }
+            "error"  => "child exited #{status.exitstatus} with no result: #{Text.last_lines(output, 5)}" }
         end
 
         def child_check_args(dir, binary, match, shrink_budget)
@@ -65,7 +69,7 @@ module Hecks
         def cargo_build
           cargo, status = Open3.capture2e("cargo", "build", "--no-default-features", "--features",
                                           Generator::DIRECTORY, chdir: @scratch)
-          return [nil, rust_failure("rust_build", cargo.lines.grep(/error/).first(12).join)] unless status.success?
+          return [nil, rust_failure("rust_build", compiler_errors(cargo))] unless status.success?
 
           binary = File.join(@scratch, "target/debug/rust-#{Generator::DIRECTORY}")
           FileUtils.cp(File.join(@scratch, "target/debug/rust"), binary)
@@ -74,6 +78,12 @@ module Hecks
 
         def rust_failure(mode, detail) = { "mode" => mode, "detail" => detail }
 
+        # The first dozen error lines of a compiler's output, joined.
+        def compiler_errors(output)
+          errors = output.lines.grep(COMPILER_ERROR)
+          errors.first(12).join
+        end
+
         def sync_scratch!
           FileUtils.mkdir_p(@scratch)
           sources = %w[Cargo.toml Cargo.lock src].map { |entry| File.join(@root, "rust", entry) }

data/lib/hecks/quality_control/cli/qa_generated_domains/promotion.rb

@@ -6,6 +6,9 @@ module Hecks
       # `--promote`: turns a finding's minimal domain into a stress domain under
       # `qa/stress_domains`, with notes that carry the blueprint and the finding.
       module Promotion
+        # A lowercase identifier: what a Rust module and a Cargo feature may be named.
+        IDENTIFIER = /\A[a-z][a-z0-9_]*\z/
+
         private
 
         def camelize(name) = name.split("_").map(&:capitalize).join
@@ -23,7 +26,7 @@ module Hecks
 
         def promotion_name
           name = @options[:name] || abort("#{USAGE}\n--promote needs --name")
-          return name if name.match?(/\A[a-z][a-z0-9_]*\z/)
+          return name if name.match?(IDENTIFIER)
 
           abort "--name must be a lowercase identifier (it becomes a Rust module and Cargo feature)"
         end

data/lib/hecks/quality_control/cli/qa_generated_domains.rb

@@ -37,6 +37,9 @@ module Hecks
       include Reporting
       include Blueprints
 
+      # The `Hecks.bluebook` line that ends the dials preamble of the ledger's bluebook.
+      BLUEBOOK_DECLARATION = /^Hecks\.bluebook/
+
       EXIT_OK = 0
       EXIT_ERROR = 1
       EXIT_FOUND = 2
@@ -98,7 +101,7 @@ module Hecks
       # @return [Boolean] false when the dials turn the step off, true once they are applied
       def dials_on?
         dials_path = File.join(@root, "lib/hecks/quality_control/quality_control.bluebook")
-        eval(File.read(dials_path).split(/^Hecks\.bluebook/).first, TOPLEVEL_BINDING, dials_path)
+        eval(File.read(dials_path).split(BLUEBOOK_DECLARATION).first, TOPLEVEL_BINDING, dials_path)
         # rubocop:enable Security/Eval
         per_tick = Integer(@env.fetch("QA_GENERATED_DOMAINS_PER_TICK", dial(:GENERATED_DOMAINS_PER_TICK, 0)))
         if per_tick.zero?

data/lib/hecks/quality_control/cli/qa_log_bug/proof.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../../../text"
 
 module Hecks
   module QualityControlCli
@@ -8,21 +9,33 @@ module Hecks
       # The proof `bug.log` demands before it writes anything: the demonstration must fail when run,
       # or, with `--reproduced no`, must at least look like runnable code.
       module Proof
+        # A command word that starts runnable code: a script path, an interpreter or a shell.
+        RUNNABLE_COMMAND = %r{\A(bundle|bin/|\./|rspec|ruby|sh|bash|zsh|python3?|node|cargo)\b}
+
+        # A source file name: Ruby, shell, Python, Rust or JavaScript.
+        SOURCE_FILE = /\.(rb|sh|py|rs|js)\b/
+
         private
 
         # Only used with `--reproduced no`, which never runs the string: a file path, an interpreter
         # or shell invocation, or a `Hecks::Fuzzing::Replay` snippet counts as code; prose does not.
         def looks_runnable?(str)
-          first = str.to_s.strip.split(/\s+/).first.to_s
+          first = first_word(str)
           return true if first.start_with?("/") && File.exist?(first)
           return true if File.exist?(File.expand_path(first, @root))
-          return true if first.match?(%r{\A(bundle|bin/|\./|rspec|ruby|sh|bash|zsh|python3?|node|cargo)\b})
-          return true if str.match?(/\.(rb|sh|py|rs|js)\b/)
+          return true if first.match?(RUNNABLE_COMMAND)
+          return true if str.match?(SOURCE_FILE)
           return true if str.include?("Hecks::Fuzzing::Replay")
 
           false
         end
 
+        # The first whitespace-separated word of `str`, or `""` for none.
+        def first_word(str)
+          words = str.to_s.strip.split(Text::WHITESPACE)
+          words.first.to_s
+        end
+
         # Runs through `sh -c` from the repository root; the output tail prints either way.
         def prove(options)
           return skip_proof(options[:demonstration]) if options[:reproduced] == "no"

data/lib/hecks/quality_control/cli/qa_mine_combinations/booting.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "open3"
+require_relative "../../../text"
 
 module Hecks
   module QualityControlCli
@@ -49,7 +50,7 @@ module Hecks
           output, = Open3.capture2e(*Child.argv(@root, "qa_generated_domains", "--check", dir, "--seeds", "0"),
                                     chdir: @root)
           line = output.lines.reverse.find { |candidate_line| candidate_line.start_with?(RESULT_MARKER) }
-          return "boot check produced no result: #{output.lines.last(5).join.strip}" unless line
+          return "boot check produced no result: #{Text.last_lines(output, 5)}" unless line
 
           result = JSON.parse(line.delete_prefix(RESULT_MARKER))
           result["status"] == "invalid" ? result["error"] : nil
@@ -82,7 +83,8 @@ module Hecks
         end
 
         def first_hypothesis_line(candidate)
-          candidate[:hypothesis].to_s.lines.map(&:strip).find { |line| !line.empty? && !line.start_with?("#") }
+          lines = candidate[:hypothesis].to_s.lines
+          lines.map(&:strip).find { |line| !line.empty? && !line.start_with?("#") }
         end
 
         def new_pairs_for(candidate)

data/lib/hecks/quality_control/cli/qa_mutate.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require_relative "../../fuzzing/qa_settings"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control target.mutate`: mutation testing of the Rust
+    # kernel. `cargo mutants` changes one operator or return value at a time and runs the tests; a
+    # mutant they do not catch is a line no test pins.
+    #
+    # `--from-dials` takes the files from the `mutation_files` dial, which is how
+    # `hecks quality_control sweep.tick` runs it; an empty list turns the step off. Mutants named in
+    # `mutation_equivalent` behave the same as the original code, so they are never run.
+    #
+    # Exit codes: 0 every mutant caught; 2 a mutant missed or timed out; 1 an operational error.
+    class QaMutate
+      EXIT_OK = 0
+      EXIT_ERROR = 1
+      EXIT_FOUND = 2
+
+      USAGE = "usage: hecks quality_control mutate [--file rust/src/<file>.rs ...] [--from-dials]"
+
+      # cargo-mutants' own exit statuses: 2 a mutant missed, 3 one timed out.
+      CARGO_FOUND = [2, 3].freeze
+
+      # The cargo-mutants outcome files, in the order the report lists them.
+      OUTCOMES = %w[caught missed timeout unviable].freeze
+
+      # Runs cargo-mutants over the files and reports.
+      #
+      # @param argv [Array<String>] `--file` paths, or `--from-dials`
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `HECKS_QA_SETTINGS_PATH` reads another settings file;
+      #   `QA_MUTATION_FILES` overrides the files of `--from-dials`
+      # @return [Integer] 0 every mutant caught, 2 one survived, 1 an operational error
+      def self.call(argv, root:, env: ENV)
+        new(root: root, env: env).call(argv)
+      end
+
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `HECKS_QA_SETTINGS_PATH` reads another settings file;
+      #   `QA_MUTATION_FILES` overrides the files of `--from-dials`
+      def initialize(root:, env: ENV)
+        @root = root
+        @env = env
+      end
+
+      # @param argv [Array<String>] `--file` paths, or `--from-dials`
+      # @return [Integer] the exit status
+      def call(argv)
+        return usage(EXIT_OK) if %w[-h --help].include?(argv.first)
+
+        files = files_from(argv)
+        return usage(EXIT_ERROR) if files.nil?
+        return off if files.empty?
+
+        run(files)
+      end
+
+      private
+
+      def usage(status)
+        (status == EXIT_OK ? $stdout : $stderr).puts USAGE
+        status
+      end
+
+      def off
+        puts "mutation: off (no mutation_files)"
+        EXIT_OK
+      end
+
+      # `QA_MUTATION_FILES` (comma-separated, empty for none) overrides the dial for one run.
+      #
+      # @return [Array<String>, nil] paths relative to `rust/`, nil for an argument it does not take
+      def files_from(argv)
+        files = argv == ["--from-dials"] ? dial_files : named_files(argv)
+        files&.map { |path| relative_to_rust(path) }
+      end
+
+      # @return [Array<String>, nil] each `--file` path, nil unless argv is only `--file` pairs
+      def named_files(argv)
+        pairs = argv.each_slice(2).to_a
+        return nil if pairs.empty? || pairs.any? { |flag, path| flag != "--file" || path.nil? }
+
+        pairs.map(&:last)
+      end
+
+      def dial_files
+        override = @env["QA_MUTATION_FILES"]
+        override ? override.split(",").map(&:strip).reject(&:empty?) : settings.mutation_files
+      end
+
+      def relative_to_rust(path) = path.delete_prefix("rust/")
+
+      def settings
+        @settings ||= Hecks::Fuzzing::QaSettings.load(
+          @env.fetch("HECKS_QA_SETTINGS_PATH", Hecks::Fuzzing::QaSettings::DEFAULT_PATH)
+        )
+      end
+
+      def run(files)
+        out_dir = File.join(@root, "tmp/qa-mutants")
+        FileUtils.rm_rf(File.join(out_dir, "mutants.out"))
+        FileUtils.mkdir_p(out_dir)
+        puts "mutation: #{files.join(", ")}"
+        output, status = Open3.capture2e(*cargo_argv(files, out_dir), chdir: File.join(@root, "rust"))
+        report(output, status.exitstatus, File.join(out_dir, "mutants.out"))
+      rescue Errno::ENOENT => e
+        warn "mutation: cannot run cargo-mutants (#{e.message}); install it with `cargo install cargo-mutants`"
+        EXIT_ERROR
+      end
+
+      # `--in-place` because `pattern.rs` `include_str!`s fixtures outside `rust/`, which a copied
+      # tree lacks. cargo-mutants puts each file back as it goes; a run killed mid-mutant leaves one
+      # changed, and the next tick's clean-tree check refuses until it is reverted.
+      def cargo_argv(files, out_dir)
+        excluded = settings.mutation_equivalent.flat_map { |name| ["--exclude-re", Regexp.escape(name)] }
+        ["cargo", "mutants", "--in-place", "--no-shuffle", "--output", out_dir,
+         *files.flat_map { |file| ["--file", file] }, *excluded]
+      end
+
+      def report(output, cargo_exit, results)
+        counts = OUTCOMES.to_h { |outcome| [outcome, outcome_lines(results, outcome)] }
+        return operational_error(output, cargo_exit) unless cargo_exit.zero? || CARGO_FOUND.include?(cargo_exit)
+
+        puts summary(counts)
+        survivors = counts["missed"] + counts["timeout"]
+        survivors.empty? ? EXIT_OK : found(survivors, results)
+      end
+
+      def found(survivors, results)
+        puts "FOUND SOMETHING (#{survivors.size} mutant(s) no test caught):"
+        survivors.each { |line| puts "  #{line}" }
+        puts "full results: #{results}"
+        EXIT_FOUND
+      end
+
+      def outcome_lines(results, outcome)
+        path = File.join(results, "#{outcome}.txt")
+        File.file?(path) ? File.readlines(path, chomp: true).reject(&:empty?) : []
+      end
+
+      # Caught over caught plus missed: a timeout is reported beside it, and an unviable mutant
+      # did not compile, so no test was asked about it.
+      def summary(counts)
+        caught, missed = counts.values_at("caught", "missed").map(&:size)
+        rate = (caught + missed).positive? ? format("%.1f%%", 100.0 * caught / (caught + missed)) : "n/a"
+        parts = OUTCOMES.map { |outcome| "#{counts[outcome].size} #{outcome}" }
+        "mutation: #{parts.join(", ")}; kill rate #{rate}"
+      end
+
+      def operational_error(output, cargo_exit)
+        warn output
+        warn "mutation: cargo mutants ended with status #{cargo_exit.inspect}"
+        EXIT_ERROR
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_sweep/all_mode/report.rb

@@ -11,6 +11,9 @@ module Hecks
           # truth that the report prints verbatim, so scraping it here cannot disagree.
           RESOLVED_DEPTH_LINE = /^resolved depth: seeds=(\d+) steps=(\d+) \(clean_streak=(\d+)\)$/
 
+          # A `QA_SWEEP_TRACE` line a child printed.
+          TRACE_LINE = /^\[qa_sweep_trace /
+
           # Parsed from a child's `resolved modes:` line; wave-2 candidates come from the parent's
           # own inference, not from this.
           RESOLVED_MODES_LINE = /^resolved modes: (\S*) \(capabilities=([^;)]*)(?:; deferred=([^)]*))?\)$/
@@ -102,7 +105,7 @@ module Hecks
             puts
             puts "QA_SWEEP_TRACE output (by target, in sweep order):"
             results.each do |r|
-              trace_lines = r[:output].lines.grep(/^\[qa_sweep_trace /)
+              trace_lines = r[:output].lines.grep(TRACE_LINE)
               next if trace_lines.empty?
 
               puts "  #{r[:target]}:"

data/lib/hecks/quality_control/cli/qa_sweep/parsing.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../../../text"
 require_relative "parsing/validation"
 
 module Hecks
@@ -98,7 +99,7 @@ module Hecks
         end
 
         def parse_modes(value)
-          names = value.to_s.split(",").map(&:strip).reject(&:empty?).map(&:to_sym)
+          names = Text.comma_list(value).map(&:to_sym)
           abort "#{USAGE}\n--modes needs at least one mode name" if names.empty?
 
           known = Hecks::Fuzzing::TargetCapabilities::MODE_REQUIREMENTS.keys

data/lib/hecks/quality_control/cli/qa_sweep.rb

@@ -45,6 +45,9 @@ module Hecks
       EXIT_ERROR = 1
       EXIT_FOUND_SOMETHING = 2
 
+      # A character a filename component may not carry.
+      UNSAFE_FILENAME_CHARACTER = /[^A-Za-z0-9_.-]/
+
       USAGE = "usage: hecks quality_control ask run [target=<reference>] arguments=\"[--seeds N] [--steps N] " \
               "[--adversarial FRACTION] [--role-draw FRACTION] [--dry-run FRACTION] " \
               "[--self-consistency true|false] [--modes a,b,c]\"\n       " \
@@ -156,7 +159,7 @@ module Hecks
       # what is stored as the
       # `Target`/`Sweep` reference itself.
       def filesystem_safe_component(reference)
-        reference.gsub(/[^A-Za-z0-9_.-]/, "-")
+        reference.gsub(UNSAFE_FILENAME_CHARACTER, "-")
       end
 
       # One target, start to finish.