hecks 3.5.0 → 3.7.0

data/lib/hecks/tools/journal_compaction.rb

@@ -24,22 +24,28 @@ module Hecks
         argv = argv.dup
         force = argv.delete("--force")
         domain = argv.shift
-        if domain.nil? || !Dir.exist?(domain)
-          warn "hecks compact: no such domain #{domain.inspect}"
-          warn "usage: hecks compact <domain> [aggregate_name ...] [--force]"
-          return 1
-        end
-        wanted = argv.dup
+        return refuse_domain(domain) if domain.nil? || !Dir.exist?(domain)
+
+        compact_domain(domain, argv.dup, force)
+      end
+
+      # @return [Integer] 1, after printing why and how to call it
+      def refuse_domain(domain)
+        warn "hecks compact: no such domain #{domain.inspect}"
+        warn "usage: hecks compact <domain> [aggregate_name ...] [--force]"
+        1
+      end
 
-        registry = Hecks.boot(domain).registry
-        candidates = candidates(registry, wanted)
-        if candidates.empty?
+      # @return [Integer] 0
+      def compact_domain(domain, wanted, force)
+        found = candidates(Hecks.boot(domain).registry, wanted)
+        if found.empty?
           puts "hecks compact: no Postgres/Sqlite-backed aggregate matched " \
-               "#{wanted.empty? ? '(any)' : wanted.inspect} in #{domain}"
+               "#{wanted.empty? ? "(any)" : wanted.inspect} in #{domain}"
           return 0
         end
 
-        candidates.each { |candidate| compact_candidate(candidate, force: force) }
+        found.each { |candidate| compact_candidate(candidate, force: force) }
         0
       end
 
@@ -47,19 +53,24 @@ module Hecks
       # @param wanted [Array<String>] aggregate names, or empty for every aggregate
       # @return [Array<Hash>] each compactable aggregate and its adapter
       def candidates(registry, wanted)
-        registry.bluebooks.each_with_object([]) do |(domain_name, bluebook), all|
-          bluebook.aggregates.each do |aggregate|
-            next unless wanted.empty? || wanted.include?(aggregate.hecks_name) || wanted.include?(aggregate.storage_name)
+        registry.bluebooks.flat_map do |domain_name, bluebook|
+          bluebook.aggregates.filter_map { |aggregate| candidate_for(registry, domain_name, aggregate, wanted) }
+        end
+      end
 
-            repository = registry.repository(domain_name, aggregate)
-            next unless repository.is_a?(Hecks::Ports::Persistence::AppendOnly)
+      # @return [Hash, nil] the aggregate and its adapter, when it is wanted and compactable
+      def candidate_for(registry, domain_name, aggregate, wanted)
+        return unless wanted.empty? || wanted.include?(aggregate.hecks_name) || wanted.include?(aggregate.storage_name)
 
-            adapter = repository.adapter
-            next unless adapter.respond_to?(:compact_entries!) && adapter.respond_to?(:checkpoint)
+        repository = registry.repository(domain_name, aggregate)
+        return unless repository.is_a?(Hecks::Ports::Persistence::AppendOnly)
 
-            all << { aggregate: aggregate, adapter: adapter }
-          end
-        end
+        adapter = repository.adapter
+        { aggregate: aggregate, adapter: adapter } if compactable?(adapter)
+      end
+
+      def compactable?(adapter)
+        adapter.respond_to?(:compact_entries!) && adapter.respond_to?(:checkpoint)
       end
 
       # @return [void]
@@ -67,23 +78,21 @@ module Hecks
         aggregate = candidate[:aggregate]
         adapter   = candidate[:adapter]
         through   = adapter.checkpoint
-
         if through <= adapter.compacted_through
-          puts "SKIP #{aggregate.storage_name}: nothing new to compact (already compacted through #{through})"
-          return
-        end
-
-        unless force
-          puts "DRY RUN #{aggregate.storage_name}: would delete journal entries through sequence " \
-               "#{through} (compacted_through is currently #{adapter.compacted_through}); current " \
-               "state (#{adapter.count} records) is unaffected. Re-run with --force to apply."
-          return
+          return puts("SKIP #{aggregate.storage_name}: nothing new to compact (already compacted through #{through})")
         end
+        return puts(dry_run_message(aggregate, adapter, through)) unless force
 
         removed = adapter.compact_entries!(through: through)
         puts "COMPACTED #{aggregate.storage_name}: deleted #{removed} journal entries through " \
              "sequence #{through}; #{adapter.count} records preserved"
       end
+
+      def dry_run_message(aggregate, adapter, through)
+        "DRY RUN #{aggregate.storage_name}: would delete journal entries through sequence " \
+          "#{through} (compacted_through is currently #{adapter.compacted_through}); current " \
+          "state (#{adapter.count} records) is unaffected. Re-run with --force to apply."
+      end
     end
   end
 end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Hecks
+  module Tools
+    module Lanes
+      # The files the `Lane` rows project into a checkout: a ruleset for each guarded lane and the
+      # promotion workflow. It writes them, or with `check` compares them and writes nothing.
+      class Files
+        # @param root [String] the checkout
+        def initialize(root)
+          @root = root
+        end
+
+        # @return [Hash{String => String}] each file's absolute path to the text it should hold
+        def projection
+          rulesets.merge(workflow(Lanes::WORKFLOW, "follows") { |lanes| Lanes.workflow(lanes) })
+                  .merge(workflow(Lanes::WATCH_WORKFLOW, "alert_after") { |lanes| WatchWorkflow.text(lanes) })
+        end
+
+        # @param files [Hash{String => String}] the projection
+        # @return [Array<String>] ruleset files that no row of a guarded lane accounts for
+        def leftover(files)
+          Dir[File.join(@root, Lanes::RULESETS, "*.json")].reject { |path| files.key?(path) }
+        end
+
+        # @param check [Boolean] whether to only compare
+        # @return [Integer] 0, or 1 when `check` finds a file out of date
+        def run(check)
+          files = projection
+          stale = files.reject { |path, text| File.exist?(path) && File.read(path) == text }.keys
+          extra = leftover(files)
+          return report(stale + extra, files.size) if check
+
+          write(files, stale, extra)
+          0
+        end
+
+        private
+
+        def rulesets
+          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.
+        def workflow(path, column)
+          lanes = Lanes.lanes.reject { |lane| lane[column].to_s.empty? }
+          lanes.empty? ? {} : { File.join(@root, path) => yield(lanes) }
+        end
+
+        def ruleset_path(name) = File.join(@root, Lanes::RULESETS, "#{name}.json")
+
+        def write(files, stale, extra)
+          stale.each do |path|
+            FileUtils.mkdir_p(File.dirname(path))
+            File.write(path, files.fetch(path))
+          end
+          extra.each { |path| File.delete(path) }
+          (stale + extra).each { |path| puts "wrote #{relative(path)}" }
+          puts "lanes: #{Lanes.lanes.size} lanes, every file current" if (stale + extra).empty?
+        end
+
+        def report(out_of_date, count)
+          if out_of_date.empty?
+            puts "lanes: #{count} files, every one current"
+            return 0
+          end
+
+          warn "lanes: out of date: #{out_of_date.map { |path| relative(path) }.join(", ")} " \
+               "(run hecks regeneration_run.project_lanes)"
+          1
+        end
+
+        def relative(path) = path.delete_prefix("#{@root}/")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    module Lanes
+      # The rulesets GitHub holds for the guarded lanes, compared with the projection and, when
+      # confirmed, made to match it: the one step of `project_lanes` that changes GitHub.
+      class Live
+        # @param github [Hecks::Adapters::GithubRulesets] reads and writes GitHub's rulesets
+        def initialize(github)
+          @github = github
+        end
+
+        # @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.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?
+
+          warn "lanes: GitHub differs from the model (add --confirm to make it match)"
+          1
+        end
+
+        private
+
+        # @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?
+          return differences unless confirm
+
+          puts "#{projected["name"]}: #{@github.apply(projected)}"
+          []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+
+module Hecks
+  module Tools
+    module Lanes
+      # The `Lane` rows of the Vocabulary chapter, checked against what the projection can express.
+      module Rows
+        module_function
+
+        # @return [Array<Hash{String => String}>] the `Lane` rows
+        # @raise [SystemExit] when a row names a pusher or a lane the projection cannot express
+        def all
+          rows = Hecks::Vocabulary.rows("Lane")
+          names = rows.map { |lane| lane["name"] }
+          rows.each do |lane|
+            problem = problem_with(lane, names)
+            abort "lanes: #{problem}" if problem
+          end
+        end
+
+        # @param lane [Hash{String => String}] a `Lane` row
+        # @param names [Array<String>] every lane's name
+        # @return [String, nil] what the projection cannot express about the row, or nil
+        def problem_with(lane, names)
+          name = lane["name"]
+          return "#{name} has pushers #{lane["pushers"].inspect}" unless Lanes::PUSHERS.include?(lane["pushers"])
+          return "#{name} has guarded #{lane["guarded"].inspect}" unless %w[yes no].include?(lane["guarded"])
+          return "#{name} has alert_after #{lane["alert_after"].inspect}, not whole hours" unless hours?(lane)
+
+          follows_problem(lane, names)
+        end
+
+        # @return [Boolean] whether `alert_after` is empty (never late) or whole hours
+        def hours?(lane) = lane["alert_after"].to_s.match?(/\A\d*\z/)
+
+        def follows_problem(lane, names)
+          follows = lane["follows"].to_s
+          "#{lane["name"]} follows #{follows.inspect}, which is not a Lane row" unless follows.empty? || names.include?(follows)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+require_relative "../../quality_control/adapters/github_checks"
+
+module Hecks
+  module Tools
+    module Lanes
+      # The ruleset GitHub is given for a guarded lane.
+      #
+      # A guarded lane cannot be deleted or rewound, and a `green` lane takes only a commit on
+      # which every `RequiredCheck` of the Vocabulary chapter has already passed. No actor is let
+      # 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
+
+        module_function
+
+        # @param lane [Hash{String => String}] a guarded `Lane` row
+        # @return [Hash] the ruleset GitHub is given for it
+        def build(lane)
+          { "name" => "lane-#{lane["name"]}", "target" => "branch", "enforcement" => "active",
+            "conditions" => { "ref_name" => { "include" => ["refs/heads/#{lane["name"]}"], "exclude" => [] } },
+            "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)
+          lane["pushers"] == "green" ? [*FIXED, required_checks] : FIXED
+        end
+
+        # @return [Hash] the rule that a pushed commit has already passed every `RequiredCheck`
+        def required_checks
+          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 } }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    module Lanes
+      # The workflow that watches each lane with an alert threshold: every hour it asks
+      # `PromotionRun` whether the lane has stood behind the lane it follows for longer than its
+      # `Lane` row allows. A late lane faults the run, and the fault files a finding, one a day: the
+      # alert key carries the date, and the journal in Postgres lets the next hour see it.
+      module WatchWorkflow
+        HEADER = <<~YAML.chomp
+          name: Watch lanes
+
+          # Generated by hecks project_lanes from the Lane rows of the Vocabulary chapter. Do not hand-edit.
+          #
+          # Every hour, asks `PromotionRun` whether a lane has stood behind the lane it follows for
+          # longer than its Lane row allows (`alert_after`, in hours). The rule is decided there, not
+          # here. A late lane fails the run, files a finding (one a day) and asks Promote to try
+          # again: a promotion that was dropped is picked up within the hour, and one that still
+          # cannot go says why in its own run.
+          on:
+            schedule:
+              - cron: "17 * * * *"
+            workflow_dispatch: {}
+
+          # One watch at a time; none is cancelled.
+          concurrency:
+            group: lane-watch
+            cancel-in-progress: false
+
+          permissions:
+            contents: read
+            checks: read
+            issues: write
+            actions: write
+
+          jobs:
+        YAML
+
+        module_function
+
+        # @param watched [Array<Hash{String => String}>] the lanes that have an alert threshold
+        # @return [String] the workflow
+        def text(watched)
+          [HEADER, *watched.flat_map { |lane| job(lane["name"]) }].join("\n") << "\n"
+        end
+
+        # @param name [String] a watched lane's name
+        # @return [Array<String>] the job that watches it
+        def job(name)
+          ["  watch_#{name}:", "    runs-on: ubuntu-latest", "    timeout-minutes: 10", "    steps:",
+           *setup_steps, *watch_step(name), *retry_step(name)]
+        end
+
+        # A watch that fails found the lane late: the promotion that should have moved it may
+        # have been dropped, so Promote is asked again. It judges the commits itself; this
+        # decides nothing.
+        def retry_step(name)
+          ["      - name: Ask Promote to try #{name} again", "        if: failure()", "        env:",
+           "          GH_TOKEN: ${{ github.token }}", "        run: gh workflow run promote.yml"]
+        end
+
+        def setup_steps
+          ["      - uses: actions/checkout@v4", "        with:",
+           "          # Full history: the lag is read from the commits one lane has and the other lacks.",
+           "          fetch-depth: 0",
+           "      - uses: ./.github/actions/setup-ruby",
+           "      - uses: ./.github/actions/hecks-environment", "        with:",
+           "          database: ${{ secrets.HECKS_JOURNAL_DATABASE }}"]
+        end
+
+        def watch_step(name)
+          ["      - name: Watch #{name}", "        env:", "          GH_TOKEN: ${{ github.token }}",
+           "          HECKS_FINDINGS_REPO: ${{ github.repository }}", "        run: >-",
+           "          bundle exec exe/hecks promotion_run.watch lane=#{name}",
+           "          run=watch-#{name}-${{ github.run_id }}-${{ github.run_attempt }}",
+           "          alert_key=#{name}-lag-$(date -u +%Y-%m-%d) --wait"]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    module Lanes
+      # The workflow that promotes each lane that follows another: it runs after CI on the lane a
+      # lane follows and asks `PromotionRun` to move the lane. The rule that decides a promotion is
+      # `PromotionRun.Accept`, not anything written here.
+      module Workflow
+        HEADER = <<~YAML.chomp
+          name: Promote
+
+          # Generated by hecks project_lanes from the Lane rows of the Vocabulary chapter. Do not hand-edit.
+          #
+          # After CI finishes on a push to the lane a lane follows, asks `PromotionRun` to move the
+          # lane onto the newest commit of that lane every RequiredCheck passed on. Which commit may
+          # go is decided there (every RequiredCheck green on that exact commit, a fast-forward of
+          # the lane), not here. The run is not tied to the commit that started it: a run that is
+          # dropped, beaten to the lane, or started by a commit still red finds the same answer, so
+          # no certified commit waits on a push that may never come.
+        YAML
+
+        module_function
+
+        # @param promoted [Array<Hash{String => String}>] the lanes that follow another
+        # @return [String] the workflow
+        def text(promoted)
+          sources = promoted.map { |lane| lane["follows"] }.uniq
+          [HEADER, *trigger(sources), *promoted.flat_map { |lane| job(lane) }].join("\n") << "\n"
+        end
+
+        # @param sources [Array<String>] the lanes whose CI run starts a promotion
+        # @return [Array<String>] the `on:` through `jobs:` lines
+        def trigger(sources)
+          ["on:", "  workflow_dispatch: {}", "  workflow_run:", "    workflows: [CI]", "    types: [completed]",
+           "    branches: [#{sources.join(", ")}]", "",
+           "# One promotion at a time, in the order the pushes finished; none is cancelled.",
+           "concurrency:", "  group: promote", "  cancel-in-progress: false", "",
+           "permissions:", "  contents: write", "  checks: read", "", "jobs:"]
+        end
+
+        # @param lane [Hash{String => String}] a lane that follows another
+        # @return [Array<String>] the job that promotes it
+        def job(lane)
+          name = lane["name"]
+          ["  promote_#{name}:", "    runs-on: ubuntu-latest", "    timeout-minutes: 15",
+           *condition, "    steps:", *checkout_steps, *promote_step(name)]
+        end
+
+        # Which events may start a promotion.
+        def condition
+          ["    # A run that did not finish green reports no commit worth promoting. Only a push of this",
+           "    # repository counts: the run of a fork's pull request from a branch named like the lane",
+           "    # also reports that branch name, and its code must never meet the token that moves the lane.",
+           "    # A by-hand run, or one the watch asked for, starts from no workflow run and needs no check.",
+           "    if: >-", "      github.event_name == 'workflow_dispatch' || (",
+           "      github.event.workflow_run.conclusion == 'success' &&",
+           "      github.event.workflow_run.event == 'push' &&",
+           "      github.event.workflow_run.head_repository.full_name == github.repository)"]
+        end
+
+        def checkout_steps
+          ["      - uses: actions/checkout@v4", "        with:",
+           "          ref: ${{ github.event.workflow_run.head_sha }}",
+           "          # Full history: the fast-forward test needs both ends of the lane as real objects.",
+           "          fetch-depth: 0",
+           "      - uses: ./.github/actions/setup-ruby", "      - uses: ./.github/actions/hecks-environment"]
+        end
+
+        def promote_step(name)
+          ["      - name: Promote #{name}", "        env:", "          GH_TOKEN: ${{ github.token }}",
+           "        run: >-",
+           "          bundle exec exe/hecks promotion_run.promote lane=#{name}",
+           "          run=#{name}-${{ github.event.workflow_run.head_sha || github.run_id }} --confirm --wait"]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/lanes.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+require_relative "../tools"
+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`), 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`.
+    #
+    # Without a flag the files are written. `--check` writes nothing and answers 1 for each file
+    # that differs, which is the drift gate. `--live` compares the rulesets GitHub holds with the
+    # projection and writes no file; with `--confirm` as well it creates or updates them, the one
+    # step that changes GitHub.
+    module Lanes
+      # Where the projected rulesets and workflows live, relative to the checkout.
+      RULESETS = ".github/rulesets"
+      WORKFLOW = ".github/workflows/promote.yml"
+      WATCH_WORKFLOW = ".github/workflows/lane-watch.yml"
+
+      # What `pushers` may say: a lane that takes any commit, or one that takes only a commit every
+      # `RequiredCheck` has passed.
+      PUSHERS = %w[anyone green].freeze
+
+      module_function
+
+      # @param argv [Array<String>] `--check`, `--live`, `--confirm`
+      # @param root [String] the checkout
+      # @param rulesets [Hecks::Adapters::GithubRulesets, nil] GitHub's rulesets; a spec replaces it
+      # @return [Integer] 0, or 1 when `--check` or `--live` finds a difference
+      # @raise [SystemExit] when a row is one the projection cannot express
+      def main(argv, root: Tools::ROOT, rulesets: nil)
+        if argv.include?("--live")
+          return Live.new(rulesets || Hecks::Adapters::GithubRulesets.new).run(argv.include?("--confirm"))
+        end
+
+        Files.new(root).run(argv.include?("--check"))
+      end
+
+      # @param root [String] the checkout
+      # @return [Hash{String => String}] each file's absolute path to the text it should hold
+      def projection(root) = Files.new(root).projection
+
+      # @param root [String] the checkout
+      # @param files [Hash{String => String}] the projection
+      # @return [Array<String>] ruleset files that no row of a guarded lane accounts for
+      def leftover(root, files) = Files.new(root).leftover(files)
+
+      # @return [Array<Hash{String => String}>] the `Lane` rows
+      def lanes = Rows.all
+
+      # @param lane [Hash{String => String}] a guarded `Lane` row
+      # @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)
+    end
+  end
+end
+
+require_relative "lanes/rows"
+require_relative "lanes/ruleset"
+require_relative "lanes/workflow"
+require_relative "lanes/watch_workflow"
+require_relative "lanes/files"
+require_relative "lanes/live"

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