hecks 3.6.0 → 3.9.0

data/lib/hecks/tools/fuzz_sweep/options.rb

@@ -8,11 +8,17 @@ module Hecks
     module FuzzSweep
       # The command line of a sweep: its options, and what the chosen adapter needs.
       module Options
+        # The options that take a whole number, and the key each fills.
+        INTEGER_OPTIONS = { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers }.freeze
+
+        # The most children a Postgres sweep runs at once unless `--workers` says otherwise.
+        POSTGRES_WORKERS = 4
+
         # @param args [Array<String>] the command line, consumed
-        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter` and `domain`; nil after a
-        #   refusal
+        # @return [Hash, nil] `seeds`, `steps`, `workers`, `adapter`, `persist` and `domain`; nil
+        #   after a refusal
         def parse(args)
-          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil }
+          options = { seeds: 20, steps: 30, workers: nil, adapter: :memory, domain: nil, persist: false }
           until args.empty?
             apply_option(options, args.shift, args)
             return nil unless adapter_known?(options[:adapter])
@@ -22,11 +28,9 @@ module Hecks
 
         # Records one command-line word in `options`, taking its value from `rest` when it has one.
         def apply_option(options, arg, rest)
-          case arg
-          when "--seeds" then options[:seeds] = Integer(rest.shift)
-          when "--steps" then options[:steps] = Integer(rest.shift)
-          when "--workers" then options[:workers] = Integer(rest.shift)
-          when "--adapter" then options[:adapter] = rest.shift.to_s.downcase.to_sym
+          if (key = INTEGER_OPTIONS[arg]) then options[key] = Integer(rest.shift)
+          elsif arg == "--persist-regressions" then options[:persist] = true
+          elsif arg == "--adapter" then options[:adapter] = rest.shift.to_s.downcase.to_sym
           else options[:domain] = arg
           end
         end
@@ -44,11 +48,18 @@ module Hecks
           options[:adapter] != :postgres || postgres_reachable?
         end
 
-        # One child per core; a real Postgres runs one at a time.
+        # One child per core. A real Postgres is capped, because each child holds its own
+        # connections and its own scratch schema, and runs one at a time on macOS, where libpq
+        # segfaults when a forked child connects.
         #
         # @return [Integer] how many children may run at once
         def worker_count(options)
-          options[:workers] || (options[:adapter] == :postgres ? 1 : Etc.nprocessors)
+          options[:workers] || (options[:adapter] == :postgres ? postgres_workers : Etc.nprocessors)
+        end
+
+        # @return [Integer] the children a Postgres sweep runs at once by default
+        def postgres_workers
+          RUBY_PLATFORM.include?("darwin") ? 1 : [Etc.nprocessors, POSTGRES_WORKERS].min
         end
 
         # `postgres` needs a reachable local server and is slower per dispatch, so pass smaller

data/lib/hecks/tools/fuzz_sweep/reporting.rb

@@ -51,9 +51,17 @@ module Hecks
         def report_findings(result)
           grouped = result.failures.group_by { |failure| failure[:signature] }
           puts "   #{grouped.size} distinct finding(s):"
+          shrunk = shrink_groups(result, grouped.values)
+          persist_regressions(result, shrunk) if result.persist
+        end
+
+        # Prints each finding and saves its shrunk repro.
+        #
+        # @return [Array<Hash>] the findings, with their shrunk `:steps`
+        def shrink_groups(result, groups)
           save_dir = save_directory(result)
-          grouped.each_value.with_index(1) do |group, number|
-            print_finding(group, number, result.seeds)
+          groups.each_with_index.map do |group, index|
+            print_finding(group, index + 1, result.seeds)
             save_finding(result, group.min_by { |failure| failure[:steps].length }, save_dir)
           end
         end
@@ -71,11 +79,25 @@ module Hecks
         end
 
         # Shrinks the smallest failing sequence of a finding and saves it as a repro script.
+        #
+        # @return [Hash] the finding, with its shrunk `:steps`
+        def repro_path(result, finding, save_dir) = File.join(save_dir, "#{result.name}-seed#{finding[:seed]}.json")
+
         def save_finding(result, smallest, save_dir)
           shrunk = shrink(result.domain, smallest[:steps], smallest[:signature], result.adapter)
-          save_path = File.join(save_dir, "#{result.name}-seed#{smallest[:seed]}.json")
+          save_path = repro_path(result, smallest, save_dir)
           write_script(shrunk, save_path, smallest[:seed], result.name)
           print_saved(smallest[:steps].length, shrunk.length, "hecks run #{result.domain} #{save_path}")
+          smallest.merge(steps: shrunk)
+        end
+
+        # Keeps one minimized repro per distinct finding. Findings that shrank to the same thing
+        # collapse here, and one already kept from an earlier run is left alone.
+        def persist_regressions(result, shrunk)
+          Hecks::Fuzzing::FailureTriage.dedupe(shrunk).each do |finding|
+            path = Hecks::Fuzzing::FailureTriage.persist(result.root, result.name, finding)
+            puts(path ? "       kept regression: #{path}" : "       regression #{finding[:triage]} already kept")
+          end
         end
 
         def print_saved(from, to, command)

data/lib/hecks/tools/fuzz_sweep.rb

@@ -15,6 +15,7 @@ module Hecks
     # properties, then shrinks each distinct finding and saves it under `tmp/fuzz-failures/`.
     #
     #   hecks fuzz [domain] [--seeds N] [--steps N] [--workers N] [--adapter memory|sqlite|postgres]
+    #               [--persist-regressions]
     #
     # The sweep is single-runtime on purpose; the cross-runtime differential is
     # `spec/rust_conformance_fuzz_spec.rb`. Without a domain it sweeps every domain
@@ -40,7 +41,7 @@ module Hecks
       Draw = Struct.new(:clean, :failures, :drawn, :skipped)
 
       # What the sweep of one domain drew and found, for the final report.
-      Result = Struct.new(:domain, :name, :seeds, :drawn, :clean, :failures, :adapter, :root)
+      Result = Struct.new(:domain, :name, :seeds, :drawn, :clean, :failures, :adapter, :root, :persist)
 
       extend Options
       extend Findings
@@ -83,7 +84,16 @@ module Hecks
         require "hecks/bluebook/meta_validator"
         Hecks::Bluebook::MetaValidator.grammar_registry
         $stdout.flush
-        fuzz_in_pool(domains, workers) { |domain| fuzz_with(options, domain, root) }
+        fuzz_in_pool(domains, workers) { |domain| fuzz_in_child(options, domain, root) }
+      end
+
+      # Runs in a forked child. A Postgres child gets its own scratch schema, so children can fuzz
+      # one database at once.
+      #
+      # @return [Boolean] whether the domain was clean
+      def fuzz_in_child(options, domain, root)
+        ENV[Hecks::Fuzzing::IsolatedBoot::FUZZ_SCHEMA_ENV] = "hecks_fuzz_#{Process.pid}" if options[:adapter] == :postgres
+        fuzz_with(options, domain, root)
       end
 
       # @return [Boolean] whether every domain was clean
@@ -92,29 +102,36 @@ module Hecks
       end
 
       def fuzz_with(options, domain, root)
-        fuzz_domain(domain, options[:seeds], options[:steps], options[:adapter], root)
+        fuzz_domain(domain, options, root)
       end
 
       # Draws seeds until `seeds` results execute or the draw cap is hit.
       #
       # @param domain [String] the domain directory
-      # @param seeds [Integer] how many executing seeds to ask for
-      # @param steps [Integer] how many steps each sequence asks for
-      # @param adapter [Symbol] the persistence to boot on
+      # @param options [Hash] the parsed command line: `seeds` (how many executing seeds to ask
+      #   for), `steps` (how many steps each sequence asks for), `adapter` (the persistence to boot
+      #   on) and `persist` (whether each distinct finding's minimized repro is also kept under
+      #   `spec/corpus/regressions/`)
       # @param root [String] the checkout
       # @return [Boolean] true if clean or skipped
-      def fuzz_domain(domain, seeds, steps, adapter = :memory, root = Tools::ROOT)
+      def fuzz_domain(domain, options, root = Tools::ROOT)
         domain = domain.chomp("/")
         name = File.basename(domain)
+        adapter = options[:adapter]
         puts "── #{name}#{" (#{adapter})" unless adapter == :memory}"
 
-        draw = draw_seeds(domain, seeds, steps, adapter)
+        draw = draw_seeds(domain, options[:seeds], options[:steps], adapter)
         if draw.skipped
           puts "   skipped — #{draw.skipped} (not fuzzable under :#{adapter})"
           return true
         end
 
-        report(settle_known(Result.new(domain, name, seeds, draw.drawn, draw.clean, draw.failures, adapter, root)))
+        report(settle_known(sweep_result(domain, name, draw, options, root)))
+      end
+
+      def sweep_result(domain, name, draw, options, root)
+        Result.new(domain, name, options[:seeds], draw.drawn, draw.clean, draw.failures,
+                   options[:adapter], root, options[:persist] || false)
       end
 
       # Known findings print but count as clean, so the sweep does not read as short.

data/lib/hecks/tools/lanes/files.rb

@@ -41,7 +41,7 @@ module Hecks
         private
 
         def rulesets
-          Lanes.lanes.select { |lane| lane["guarded"] == "yes" }.to_h { |lane| [ruleset_path(lane), ruleset(lane)] }
+          Lanes.rulesets.to_h { |name, ruleset| [ruleset_path(name), "#{JSON.pretty_generate(ruleset)}\n"] }
         end
 
         # The workflow at `path` for the lanes whose `column` is set, or no file if none is.
@@ -50,9 +50,7 @@ module Hecks
           lanes.empty? ? {} : { File.join(@root, path) => yield(lanes) }
         end
 
-        def ruleset_path(lane) = File.join(@root, Lanes::RULESETS, "#{lane["name"]}.json")
-
-        def ruleset(lane) = "#{JSON.pretty_generate(Lanes.ruleset(lane))}\n"
+        def ruleset_path(name) = File.join(@root, Lanes::RULESETS, "#{name}.json")
 
         def write(files, stale, extra)
           stale.each do |path|

data/lib/hecks/tools/lanes/live.rb

@@ -14,7 +14,7 @@ module Hecks
         # @param confirm [Boolean] whether to create or update the rulesets
         # @return [Integer] 0 when GitHub agrees (or was made to), else 1
         def run(confirm)
-          found = Lanes.lanes.select { |lane| lane["guarded"] == "yes" }.flat_map { |lane| sync(lane, confirm) }
+          found = Lanes.rulesets.values.flat_map { |projected| sync(projected, confirm) }
           puts "lanes: GitHub holds every guarded lane's ruleset as projected" if found.empty? && !confirm
           return 0 if found.empty?
 
@@ -24,9 +24,8 @@ module Hecks
 
         private
 
-        # @return [Array<String>] the differences left after the lane was looked at
-        def sync(lane, confirm)
-          projected = Lanes.ruleset(lane)
+        # @return [Array<String>] the differences left after the ruleset was looked at
+        def sync(projected, confirm)
           differences = @github.differences(projected, @github.named(projected["name"]))
           differences.each { |line| puts line }
           return [] if differences.empty?

data/lib/hecks/tools/lanes/ruleset.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "hecks/vocabulary"
+require_relative "../../quality_control/adapters/github_checks"
 
 module Hecks
   module Tools
@@ -12,6 +13,10 @@ module Hecks
       # past it: a push of a commit that passed is how a promotion moves the lane, and the GitHub
       # Actions app cannot be named as a bypass actor.
       module Ruleset
+        # The GitHub Actions app. A required check counts only when this app reported it, so no
+        # other app, token or person can post a passing check of the same name against a commit.
+        GITHUB_ACTIONS_APP_ID = Hecks::Adapters::GithubChecks::GITHUB_ACTIONS_APP_ID
+
         # What every guarded lane forbids: deleting it and rewinding it.
         FIXED = [{ "type" => "deletion" }, { "type" => "non_fast_forward" }].freeze
 
@@ -25,6 +30,21 @@ module Hecks
             "bypass_actors" => [], "rules" => rules(lane) }
         end
 
+        # The ruleset for the tag a guarded lane feeds. The tag follows the lane, so it may move
+        # forward, which GitHub allows under `non_fast_forward` (a descendant is not a force-push);
+        # it cannot be deleted or pointed at an older commit, and no actor is let past it.
+        #
+        # @param lane [Hash{String => String}] a guarded `Lane` row
+        # @return [Hash, nil] the ruleset GitHub is given for the tag, nil when the lane feeds none
+        def tag(lane)
+          feed = lane["feeds"].to_s
+          return if feed.empty?
+
+          { "name" => "tag-#{feed}", "target" => "tag", "enforcement" => "active",
+            "conditions" => { "ref_name" => { "include" => ["refs/tags/#{feed}"], "exclude" => [] } },
+            "bypass_actors" => [], "rules" => FIXED }
+        end
+
         # @param lane [Hash{String => String}] a `Lane` row
         # @return [Array<Hash>] the rules: the fixed ones, and the required checks of a `green` lane
         def rules(lane)
@@ -33,7 +53,9 @@ module Hecks
 
         # @return [Hash] the rule that a pushed commit has already passed every `RequiredCheck`
         def required_checks
-          contexts = Hecks::Vocabulary.rows("RequiredCheck").map { |check| { "context" => check["name"] } }
+          contexts = Hecks::Vocabulary.rows("RequiredCheck").map do |check|
+            { "context" => check["name"], "integration_id" => GITHUB_ACTIONS_APP_ID }
+          end
           { "type"       => "required_status_checks",
             "parameters" => { "strict_required_status_checks_policy" => false, "do_not_enforce_on_create" => false,
                               "required_status_checks" => contexts } }

data/lib/hecks/tools/lanes.rb

@@ -7,7 +7,8 @@ require_relative "../hecks/adapters/github_rulesets"
 module Hecks
   module Tools
     # Projects the `Lane` rows of the Vocabulary chapter into what GitHub is told about them: a
-    # ruleset for each guarded lane (`.github/rulesets/<lane>.json`) and the workflow that promotes
+    # ruleset for each guarded lane (`.github/rulesets/<lane>.json`), one for the tag such a lane
+    # feeds (`.github/rulesets/tag-<tag>.json`), and the workflow that promotes
     # each lane that follows another (`.github/workflows/promote.yml`). The workflow only runs
     # `hecks promotion_run.promote`; the rule that decides a promotion is `PromotionRun.Accept`.
     #
@@ -56,6 +57,16 @@ module Hecks
       # @return [Hash] the ruleset GitHub is given for it
       def ruleset(lane) = Ruleset.build(lane)
 
+      # @return [Hash{String => Hash}] every ruleset the rows project, by the name of its file
+      #   under `.github/rulesets`: for each guarded lane its own, and one for the tag it feeds
+      def rulesets
+        lanes.select { |lane| lane["guarded"] == "yes" }.each_with_object({}) do |lane, found|
+          found[lane["name"]] = Ruleset.build(lane)
+          tag = Ruleset.tag(lane)
+          found[tag["name"]] = tag if tag
+        end
+      end
+
       # @param promoted [Array<Hash{String => String}>] the lanes that follow another
       # @return [String] the promotion workflow
       def workflow(promoted) = Workflow.text(promoted)

data/lib/hecks/tools/mutation_run.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "../tools"
+
+module Hecks
+  module Tools
+    # Mutation-tests a domain's own checks: changes its bluebooks in small ways and reports every
+    # change that the fuzz properties, the corpus script and the behaviors tests let through.
+    #
+    #   hecks mutate <domain> [--seed N] [--budget N] [--seeds N] [--steps N] [--corpus path]
+    #                         [--operators a,b] [--min-score fraction]
+    #
+    # Exit 0 unless `--min-score` is given and the score is below it. See
+    # `Hecks::Fuzzing::Mutation`.
+    module MutationRun
+      USAGE = "usage: hecks mutate <domain> [--seed N] [--budget N] [--seeds N] [--steps N] [--corpus PATH] " \
+              "[--operators a,b] [--min-score FRACTION]"
+
+      # Each flag: the option it sets and how its value is read.
+      FLAGS = {
+        "--seed"      => [:seed, :integer],
+        "--budget"    => [:budget, :integer],
+        "--seeds"     => [:seeds, :integer],
+        "--steps"     => [:steps, :integer],
+        "--corpus"    => [:corpus, :text],
+        "--operators" => [:operators, :names],
+        "--min-score" => [:min_score, :fraction]
+      }.freeze
+
+      READERS = {
+        integer:  ->(text) { Integer(text) },
+        fraction: ->(text) { Float(text) },
+        text:     ->(text) { text },
+        names:    ->(text) { text.to_s.split(",").map(&:to_sym) }
+      }.freeze
+
+      module_function
+
+      # @param argv [Array<String>] the domain directory, then the flags
+      # @param root [String] the checkout (unused: the domain is named by path)
+      # @return [Integer] 0 when the score is high enough or no minimum was asked, 1 when it is not
+      # @raise [SystemExit] with the usage line when an argument is missing or unknown
+      def main(argv, root: Tools::ROOT)
+        _ = root
+        require "hecks"
+        require "hecks/fuzzing/mutation"
+        args = argv.dup
+        domain = args.shift or abort USAGE
+        options = parse(args)
+
+        report = Hecks::Fuzzing::Mutation::Run.call(domain, **options.except(:min_score))
+        puts report
+        report.passes?(options.fetch(:min_score, 0.0)) ? 0 : 1
+      end
+
+      # @param args [Array<String>] the flags, consumed
+      # @return [Hash] the options the flags set
+      def parse(args)
+        options = {}
+        apply_flag(options, args.shift, args) until args.empty?
+        options
+      end
+
+      # Records one flag in `options`, taking its value from `rest`.
+      def apply_flag(options, flag, rest)
+        key, kind = FLAGS.fetch(flag) { abort "unknown argument #{flag.inspect}\n#{USAGE}" }
+        options[key] = READERS.fetch(kind).call(rest.shift)
+      rescue ArgumentError, TypeError
+        abort "#{flag} needs a #{kind == :fraction ? "number" : "value"}\n#{USAGE}"
+      end
+    end
+  end
+end

data/lib/hecks/tools.rb

@@ -39,6 +39,7 @@ module Hecks
       "heki_compact"                   => ["tools/heki_compaction", "HekiCompaction"],
       "fuzz"                           => ["tools/fuzz_sweep", "FuzzSweep"],
       "generate"                       => ["tools/sequence_script", "SequenceScript"],
+      "mutate"                         => ["tools/mutation_run", "MutationRun"],
       "corpus"                         => ["tools/corpus_report", "CorpusReport"],
       "evolve"                         => ["tools/evolve_run", "EvolveRun"],
       "query_ir"                       => ["tools/query_ir_run", "QueryIrRun"],

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.6.0".freeze
+  VERSION = "3.9.0".freeze
 end

data/lib/hecks/vocabulary.rb

@@ -51,7 +51,7 @@ module Hecks
       ].freeze,
       "CiGate" => [
         {"name"=>"runtime_changed", "workflow"=>"ci.yml", "mode"=>"touches", "pattern"=>"^lib/hecks/runtime/", "push"=>"before_sha", "label"=>"does this change touch lib/hecks/runtime/**?"}.freeze,
-        {"name"=>"postgres_io_relevant_changed", "workflow"=>"ci-postgres-io-parallel.yml", "mode"=>"skips_unless", "pattern"=>"^(docs/|editors/|release/|deploy/|\\.claude/|\\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"before_sha", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
+        {"name"=>"postgres_io_relevant_changed", "workflow"=>"ci-postgres-io-parallel.yml", "mode"=>"skips_unless", "pattern"=>"^(docs/|editors/|release/|deploy/|\\.claude/|\\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\\.rubocop\\.yml$|\\.rubocop_todo\\.yml$|\\.mcp\\.json$|\\.rspec-local\\.example$|README\\.md$|CHANGELOG\\.md$|CONTRIBUTING\\.md$|SECURITY\\.md$|LICENSE$|\\.gitignore$)", "push"=>"skip", "label"=>"does this change touch anything rspec_postgres_io_parallel covers?"}.freeze
       ].freeze,
       "Comparison" => [
         {"symbol"=>">=", "compares_less_than"=>"true", "compares_equal"=>"false", "negated"=>"true"}.freeze,
@@ -153,6 +153,7 @@ module Hecks
         {"name"=>"guided_generation", "type"=>"Boolean", "meaning"=>"Coverage-guided generation across one sweep's seeds (`Hecks::Fuzzing::CoverageCampaign`)."}.freeze,
         {"name"=>"corpus_splice_probability", "type"=>"Numeric", "meaning"=>"Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage. Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost."}.freeze,
         {"name"=>"favor_rare_verbs", "type"=>"Integer", "meaning"=>"How many of the least-hit verbs the next seed weights up; 0 turns the lever off."}.freeze,
+        {"name"=>"runtime_coverage_feedback", "type"=>"Boolean", "meaning"=>"Whether guided generation also admits a seed to the corpus for reaching a new line or branch of the Ruby runtime (`Hecks::Fuzzing::RuntimeCoverage`), not only a new (verb, kind, state, mutation, outcome) tuple. Off by default: tracing every line slows each seed."}.freeze,
         {"name"=>"self_consistency_checks", "type"=>"Boolean", "meaning"=>"Whether `hecks quality_control query sweep.run` also runs the self-consistency pass (cold rehydration, replay idempotency, value-object JSON round trip) on the same generated sequence."}.freeze,
         {"name"=>"shrink_budget", "type"=>"Integer", "meaning"=>"Candidate replays `hecks quality_control query sweep.run` may spend shrinking one surprised check; 0 turns shrinking off. `concurrency` is never shrunk: a race does not reproduce on demand."}.freeze,
         {"name"=>"yield_weight_seconds", "type"=>"Integer", "meaning"=>"Seconds of staleness that one point of yield score is worth in `RotationPriority.pick`. Zero would make yield invisible, so pick a number that lets it matter."}.freeze,
@@ -414,6 +415,7 @@ module Hecks
         {"script"=>"fuzz", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"fuzz"}.freeze,
         {"script"=>"generate", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"generate_sequence"}.freeze,
         {"script"=>"bench", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"bench"}.freeze,
+        {"script"=>"(new)", "section"=>"Custodian", "aggregate"=>"FuzzRun", "verb"=>"mutate"}.freeze,
         {"script"=>"(new)", "section"=>"Custodian", "aggregate"=>"Era", "verb"=>"hold_first"}.freeze,
         {"script"=>"project_deploy", "section"=>"Deploy", "aggregate"=>"Recipe", "verb"=>"project"}.freeze,
         {"script"=>"lint_deploy_recipes", "section"=>"Deploy", "aggregate"=>"MakefileCheck", "verb"=>"lint"}.freeze,