hecks 5.0.0 → 7.0.0

data/lib/hecks/quality_control/cli/qa_main_gate/worktree.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "tmpdir"
+
+module Hecks
+  module QualityControlCli
+    class QaMainGate
+      # A temporary git worktree, made for one block and removed when it returns, so a gate or a fix never
+      # runs in the owner's checkout.
+      module Worktree
+        # Raised when a git command the worktree needs fails.
+        class Failed < StandardError; end
+
+        module_function
+
+        # @param root [String] the repository the worktree belongs to
+        # @param ref [String] the commit the worktree starts at
+        # @param branch [String, nil] a new branch checked out in it; nil leaves HEAD detached
+        # @yieldparam dir [String] the worktree's directory
+        # @return [Object] whatever the block returns
+        def with(root:, ref:, branch: nil)
+          dir = Dir.mktmpdir("hecks-qa-worktree-")
+          git!(root, "worktree", "add", *(branch ? ["-b", branch] : ["--detach"]), dir, ref)
+          yield dir
+        ensure
+          remove(root, dir) if dir
+        end
+
+        # @return [String] the output of one git command, stripped
+        # @raise [Failed] when git exits non-zero
+        def git!(root, *argv)
+          output, status = Open3.capture2e("git", "-C", root, *argv)
+          raise Failed, "git #{argv.join(" ")} failed: #{output.strip}" unless status.success?
+
+          output.strip
+        end
+
+        # @return [Boolean] whether git exited 0
+        def git?(root, *argv)
+          _, status = Open3.capture2e("git", "-C", root, *argv)
+          status.success?
+        end
+
+        # Removes a worktree and its directory. Nothing is answered: a removal that fails leaves the
+        # directory for `git worktree prune` to report.
+        def remove(root, dir)
+          try(root, "worktree", "remove", "--force", dir)
+          try(root, "worktree", "prune")
+          FileUtils.rm_rf(dir)
+        end
+
+        # Runs one git command and answers nothing, for the commands whose failure is not a refusal.
+        def try(root, *argv)
+          Open3.capture2e("git", "-C", root, *argv)
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../../../hecks"
+# The era subsystem does not load with core (ADR 0033); the QualityControl ledger binds it.
+require_relative "../../ports/persistence/plugins/era"
+require_relative "qa_main_gate/gate_run"
+require_relative "qa_main_gate/worktree"
+require_relative "qa_main_gate/shell"
+require_relative "qa_main_gate/sweeping"
+require_relative "qa_main_gate/logging"
+require_relative "qa_fix_main_bug"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control main_check.check_main`, the tick's main step. It runs
+    # the quick gate on local main in a temporary worktree, records the verdict against the commit, and
+    # for each red check logs one bug proven by its output. A self-contained bug is handed to
+    # `QaFixMainBug`. A commit already on record is answered from the record, so a tick that finds it again
+    # logs nothing twice.
+    #
+    # Exit 0 when main is green, 2 when a check is red (the bugs are on the ledger), 1 on an operational
+    # error. `QA_SWEEP_DOMAIN_DIR` picks the ledger, as for the other QA commands.
+    class QaMainGate
+      include Sweeping
+      include Logging
+
+      EXIT_OK = 0
+      EXIT_ERROR = 1
+      EXIT_FOUND_SOMETHING = 2
+
+      USAGE = "usage: hecks quality_control main_check.check_main"
+
+      # Runs the step.
+      #
+      # @param argv [Array<String>] no arguments
+      # @param root [String] the repository root, whose local `main` is checked
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` picks another ledger
+      # @param gate [#run] runs the quick gate in a directory and answers its results; a spec injects one
+      # @param shell [Module] the fixer, landing and push commands; a spec injects one
+      # @return [Integer] the exit status
+      def self.call(argv, root:, env: ENV, gate: GateRun, shell: Shell)
+        new(root: root, env: env, gate: gate, shell: shell).call(argv)
+      end
+
+      # @param root [String] the repository root
+      # @param env [Hash{String => String}] `QA_SWEEP_DOMAIN_DIR` picks another ledger
+      # @param gate [#run] the quick gate's runner
+      # @param shell [Module] the fixer, landing and push commands
+      def initialize(root:, env: ENV, gate: GateRun, shell: Shell)
+        @root = root
+        @domain_dir = env.fetch("QA_SWEEP_DOMAIN_DIR", File.join(root, "qa/bluebook"))
+        @gate = gate
+        @shell = shell
+      end
+
+      # @param argv [Array<String>] no arguments
+      # @return [Integer] the exit status
+      def call(argv)
+        return reject(argv) unless argv.empty?
+
+        @runtime = boot_ledger
+        sha = Worktree.git!(@root, "rev-parse", "--verify", "main")
+        recorded = recorded_verdict(sha)
+        return answer_recorded(sha, recorded) if recorded
+
+        results = Worktree.with(root: @root, ref: sha) { |dir| @gate.run(dir) }
+        judge(sha, results)
+      end
+
+      private
+
+      def reject(argv)
+        return puts(USAGE) && EXIT_OK if %w[-h --help].include?(argv.first)
+
+        warn "#{USAGE}\nthis command takes no arguments"
+        EXIT_ERROR
+      end
+
+      def boot_ledger
+        Hecks.boot(@domain_dir)
+      rescue StandardError => e
+        abort "the QualityControl ledger did not boot (#{e.class}: #{e.message})"
+      end
+
+      # @return [String, nil] `red` or `green` when the commit is on record
+      def recorded_verdict(sha)
+        row = @runtime.query("QualityControl::MainCheck.All").find { |check| check[:reference][:value] == sha }
+        row&.[](:verdict)&.[](:value)
+      end
+
+      def answer_recorded(sha, verdict)
+        puts "main at #{sha[0, 7]} was already checked: #{verdict}"
+        verdict == "red" ? EXIT_FOUND_SOMETHING : EXIT_OK
+      end
+
+      def judge(sha, results)
+        reds = results.reject(&:passed)
+        record!(sha, reds.size)
+        return green(sha, results) if reds.empty?
+
+        sweep = record_sweep(sha, results)
+        logged = reds.map { |result| log_red(sweep, result, sha) }
+        fixes = fix_self_contained(logged)
+        red(sha, logged, fixes)
+      end
+
+      def record!(sha, count)
+        ::QualityControl::MainCheck.record!(reference: { value: sha }, verdict: { value: count.zero? ? "green" : "red" },
+                                            red_checks: { value: count })
+      end
+
+      def fix_self_contained(logged)
+        logged.filter_map do |reference, disposition, fresh|
+          next unless fresh && disposition == "self_contained"
+
+          QaFixMainBug.new(runtime: @runtime, root: @root, gate: @gate, shell: @shell).fix(reference).message
+        end
+      end
+
+      def green(sha, results)
+        puts "main at #{sha[0, 7]} is green: #{results.map(&:id).join(", ")}"
+        EXIT_OK
+      end
+
+      def red(sha, logged, fixes)
+        logged.each do |reference, _, fresh|
+          puts "#{fresh ? "logged" : "already open"} #{reference} for main at #{sha[0, 7]}"
+        end
+        fixes.each { |line| puts line }
+        EXIT_FOUND_SOMETHING
+      end
+    end
+  end
+end

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_postgres_role.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "pg"
 require_relative "qa_postgres_role/ownership"
 
 module Hecks
@@ -77,6 +76,7 @@ module Hecks
       def provision(database, role)
         done = []
         skipped = []
+        require "pg"
         admin = PG.connect(dbname: "postgres")
         create_role(admin, role, done, skipped)
         take_database(admin, database, role, done, skipped)

data/lib/hecks/quality_control/cli/qa_pr_check/checking.rb

@@ -99,12 +99,11 @@ module Hecks
           "checks still running" if checks.any? { |c| c[:bucket] == "pending" }
         end
 
-        # Starts a Clearance and asks the CI port for a verdict. ClearOnPass/RefuseOnFail settle
+        # Checks a commit: the CI port gives a verdict. ClearOnPass/RefuseOnFail settle
         # the record synchronously, so `find` sees it straight away; a red one is appended to
         # `@newly_red`.
         def ask_the_ledger(pull)
-          ::QualityControl::Clearance.start!(commit: { value: pull.sha })
-          @runtime.dispatch_flat("QualityControl::Clearance.CI.Run", { commit: pull.sha })
+          ::QualityControl::Clearance.check!(commit: { value: pull.sha })
           cleared = ::QualityControl::Clearance.find(pull.sha)
           summary = cleared.summary.to_h[:value]
           return puts("#{pull.tag}: CLEARED — #{summary}") if cleared.status == "green"

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../../../hecks"
+
+module Hecks
+  module QualityControlCli
+    # The tick's push check: dispatches `PushNudge.Check` once in the Hecks domain, where Tickets
+    # keeps the Work rows, and prints that it ran. It reads refs git already holds and fetches,
+    # pushes and merges nothing. It never fails a tick: a check that could not run prints why and
+    # exits 0, since a missing nudge must not stop the sweep.
+    class QaPushNudge
+      EXIT_OK = 0
+
+      # Everything up to the first line break.
+      FIRST_LINE = /[^\n]*/
+
+      # Runs the check.
+      #
+      # @param _argv [Array<String>] unused
+      # @param root [String] the repository root, whose `lib/hecks/hecks` domain is booted
+      # @return [Integer] 0, always
+      def self.call(_argv, root:)
+        new(root: root).call
+      end
+
+      # @param root [String] the repository root
+      def initialize(root:)
+        @root = root
+      end
+
+      # @return [Integer] 0, always
+      def call
+        runtime = Hecks.boot(File.join(@root, "lib/hecks/hecks"))
+        key = "check-#{Time.now.utc.strftime("%Y%m%dT%H%M%S")}-#{Process.pid}"
+        runtime.dispatch_flat("QualityControl::PushNudge.Check", nudge: { value: key })
+        puts "push nudge: checked (#{key}); the push-due Work row is filed, revised or finished"
+        EXIT_OK
+      rescue StandardError => e
+        puts "push nudge: skipped (#{e.class}: #{first_line(e.message)})"
+        EXIT_OK
+      end
+
+      private
+
+      def first_line(text) = text[FIRST_LINE].strip
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_seed_angles/seed.rb

@@ -48,7 +48,7 @@ module Hecks
                      "banking for CI-gated differential fuzzing. rust/Cargo.toml already declares " \
                      "compiled-binary features for compliance and roster (plus meta) that " \
                      "sit unused for this purpose; examples/chess and examples/directory have no Cargo " \
-                     "feature at all — `hecks project_rust` has never regenerated a binary for either. " \
+                     "feature at all — `hecks build.project_rust!` has never regenerated a binary for either. " \
                      "Widening either list would let differential fuzzing catch a whole bug class " \
                      "Ruby-only fuzzing cannot, on domains the practice already owns.",
           citation:  "BUG#1/#3/#4 (engine-divergence bugs); spec/rust_conformance_fuzz_spec.rb DOMAINS " \

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/seat.rb

@@ -60,7 +60,7 @@ module Hecks
           # `build_rust_for` answers nil only for an undeclared feature; a declared one that fails
           # raises, so its cargo stderr is printed here.
           reason = @rust_build_failure ? @rust_build_failure.message : "rust/Cargo.toml declares no #{@feature} feature"
-          puts "note: no #{@feature} Rust binary — degrading this sweep to ruby_only. Run `hecks project_rust` for it " \
+          puts "note: no #{@feature} Rust binary — degrading this sweep to ruby_only. Run `hecks build.project_rust!` for it " \
                "and re-sweep.\n#{reason}"
           @active_modes = (@active_modes - %i[differential properties_in_differential structural_skip_report]) |
                           [:ruby_only]

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.

data/lib/hecks/quality_control/cli/qa_tick/event_pump_step.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../qa_event_pump"
+require_relative "push_nudge_step"
+
+module Hecks
+  module QualityControlCli
+    class QaTick
+      # The tick's last finding step: the event pump, which runs each attached domain's policies
+      # on the events its cursors have not yet read.
+      module EventPumpStep
+        include PushNudgeStep
+
+        private
+
+        # @return [Array<Step>] the steps after the finding steps: the push check and the pump
+        def watch_steps = push_nudge_steps + pump_steps
+
+        # @return [Array<Step>] the pump's step when the `event_pump` dial is on, else none
+        def pump_steps
+          dial(:EVENT_PUMP, false) ? [guarded("event_pump") { run_event_pump }] : []
+        end
+
+        # @return [Array(String, Integer)] the pump's output and its exit status
+        def run_event_pump
+          banner "hecks quality_control event_pump.pump!"
+          output, exit_code = run_step(->(argv) { QaEventPump.call(argv, root: @root) })
+          puts output
+          [output, exit_code]
+        end
+      end
+    end
+  end
+end