hecks 3.4.2 → 3.6.0

data/lib/hecks/hecks/adapters/git_refs.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The ref calls of the `Git` adapter: where a ref stands on the remote, whether one commit
+    # contains another, and moving a branch or a tag forward.
+    #
+    # It is mixed into `Git`, which supplies `capture`. Every name that reaches a command is
+    # checked first, and a push is never forced except for a tag the ancestry test has already
+    # allowed to move.
+    module GitRefs
+      # A branch or tag name, or a commit, as git accepts one in a refspec: no space, no option, no
+      # colon, and no `..`, so a name cannot smuggle a second ref or a flag into a command.
+      REF_PATTERN = %r{\A[0-9A-Za-z_][0-9A-Za-z_./-]*\z}
+
+      # Where a ref points on the remote, after fetching it.
+      #
+      # @param ref [String] a branch name, `refs/heads/<name>` or `refs/tags/<name>`
+      # @param remote [String] the remote to ask
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [String, nil] the commit the ref names, or nil when the remote has no such ref
+      # @raise [ConsoleCapture::Failure] when the ref is malformed or the remote cannot be reached
+      def remote_head(ref, remote: "origin", chdir: nil)
+        name = checked_ref(ref)
+        listed = capture("ls-remote", remote, name, chdir: chdir)
+        refuse("git ls-remote #{remote} #{name} failed", listed) unless listed.ok?
+
+        listed.out.lines.map { |line| line.split.first }.first
+      end
+
+      # Whether one commit is an ancestor of another, so that moving a ref from the first to the
+      # second is a fast-forward. A commit is its own ancestor.
+      #
+      # @param ancestor [String] a commit
+      # @param descendant [String] a commit
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Boolean] whether `descendant` contains `ancestor`
+      # @raise [ConsoleCapture::Failure] when git cannot tell (an unknown commit, a malformed name)
+      def ancestor?(ancestor, descendant, chdir: nil)
+        result = capture("merge-base", "--is-ancestor", checked_ref(ancestor), checked_ref(descendant), chdir: chdir)
+        return true if result.ok?
+        return false if result.status.exitstatus == 1
+
+        refuse("git merge-base failed", result)
+      end
+
+      # When the oldest commit of a range was made: the commits `newer` has that `older` lacks.
+      #
+      # Only the first-parent chain counts, so a branch merged long after it was written is dated by
+      # the merge that brought it in, not by its oldest commit: the age asked about is how long the
+      # lane has been waiting for something to land, not how long ago anyone typed it.
+      #
+      # @param older [String, nil] a commit, branch or ref, or nil for every commit of `newer`
+      # @param newer [String] a commit, branch or ref
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Integer, nil] the oldest such commit's time, in seconds since the epoch, or nil
+      #   when `newer` holds nothing `older` lacks
+      # @raise [ConsoleCapture::Failure] when git cannot read the range
+      def oldest_commit_time(older, newer, chdir: nil)
+        range = older ? "#{checked_ref(older)}..#{checked_ref(newer)}" : checked_ref(newer)
+        listed = capture("log", "--first-parent", "--reverse", "--format=%ct", range, chdir: chdir)
+        refuse("git log #{range} failed", listed) unless listed.ok?
+
+        listed.out.lines.first&.to_i
+      end
+
+      # The commits a lane may be moved onto, newest first: the first-parent chain of `newer` that
+      # `older` does not already contain.
+      #
+      # @param newer [String] the commit or ref the chain starts from
+      # @param older [String, nil] the commit the lane stands on, nil when it does not exist yet
+      # @param limit [Integer] how many commits to name at most
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Array<String>] full commit ids, newest first
+      # @raise [ConsoleCapture::Failure] when git cannot read the range
+      def recent_commits(newer, older: nil, limit: 25, chdir: nil)
+        range = older ? "#{checked_ref(older)}..#{checked_ref(newer)}" : checked_ref(newer)
+        listed = capture("rev-list", "--first-parent", "-n", Integer(limit).to_s, range, chdir: chdir)
+        refuse("git rev-list #{range} failed", listed) unless listed.ok?
+
+        listed.out.split
+      end
+
+      # Moves a remote branch to a commit, and only forward: the push is refused by the remote when
+      # the commit does not contain the branch's head, and is never forced.
+      #
+      # @param commit [String] the commit to push
+      # @param branch [String] the branch to move
+      # @param remote [String] the remote to push to
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [void]
+      # @raise [ConsoleCapture::Failure] when the remote refuses (not a fast-forward, a ruleset)
+      def fast_forward(commit, branch, remote: "origin", chdir: nil)
+        pushed = capture("push", remote, "#{checked_ref(commit)}:refs/heads/#{checked_ref(branch)}", chdir: chdir)
+        refuse("git push #{remote} #{branch} was refused", pushed) unless pushed.ok?
+      end
+
+      # Moves a tag to a commit on the remote, and only forward: a tag that points at a commit the
+      # new one does not contain is left where it is. A tag that does not yet exist is made.
+      #
+      # @param tag [String] the tag to move
+      # @param commit [String] the commit it should name
+      # @param remote [String] the remote to push to
+      # @param chdir [String, nil] a directory inside the repository
+      # @return [Symbol] `:created`, `:moved` or `:current`
+      # @raise [ConsoleCapture::Failure] when the tag stands on a commit that is not an ancestor of
+      #   `commit`, or the remote refuses
+      def move_tag(tag, commit, remote: "origin", chdir: nil)
+        name = checked_ref(tag)
+        sha = checked_ref(commit)
+        standing = remote_head("refs/tags/#{name}", remote: remote, chdir: chdir)
+        return :current if standing == sha
+
+        refuse_rewind(name, standing, sha) if standing && !ancestor?(standing, sha, chdir: chdir)
+        force_tag(name, sha, remote, chdir)
+        standing ? :moved : :created
+      end
+
+      private
+
+      def force_tag(name, sha, remote, chdir)
+        pushed = capture("push", "--force", remote, "#{sha}:refs/tags/#{name}", chdir: chdir)
+        refuse("git push #{remote} #{name} was refused", pushed) unless pushed.ok?
+      end
+
+      def refuse_rewind(name, standing, sha)
+        raise ConsoleCapture::Failure, "#{name} stands on #{standing[0, 7]}, which #{sha[0, 7]} does not contain"
+      end
+
+      def refuse(what, result)
+        raise ConsoleCapture::Failure, "#{what}: #{result.err.strip}"
+      end
+
+      def checked_ref(ref)
+        name = ref.to_s
+        return name if name.match?(REF_PATTERN) && !name.include?("..")
+
+        raise ConsoleCapture::Failure, "#{name.inspect} is not a ref name git can be given safely"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/github_rulesets.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Hecks
+  module Adapters
+    # The rulesets of the repository `gh` is pointed at, read and written through `gh api`.
+    #
+    # `Tools::Lanes` projects each guarded `Lane` row into a ruleset and uses this to compare the
+    # projection with what GitHub holds, and to create or update it. Nothing here decides what a
+    # ruleset says; it only carries a ruleset to and from GitHub. `{owner}/{repo}` is a `gh api`
+    # template resolved from the git remote.
+    class GithubRulesets
+      # The part of a ruleset a lane projects: everything else GitHub fills in (ids, links,
+      # timestamps, defaults) is left out of a comparison.
+      COMPARED = %w[name target enforcement].freeze
+
+      # @param runner [#call, nil] runs `gh` with its arguments and stdin text, answering
+      #   `[stdout, stderr, success]`; the real `gh` when nil. A spec replaces it.
+      def initialize(runner: nil)
+        @runner = runner || method(:run_gh)
+      end
+
+      # @return [Array<Hash>] every ruleset of the repository, in full
+      # @raise [RuntimeError] when `gh` is missing or refuses
+      def all
+        listed = json(call("api", "repos/{owner}/{repo}/rulesets?per_page=100"))
+        listed.map { |ruleset| json(call("api", "repos/{owner}/{repo}/rulesets/#{ruleset.fetch("id")}")) }
+      end
+
+      # @param name [String] a ruleset's name
+      # @return [Hash, nil] the ruleset of that name, or nil when the repository has none
+      def named(name) = all.find { |ruleset| ruleset["name"] == name }
+
+      # Makes the ruleset exist as projected: creates it, or updates the one of that name.
+      #
+      # @param projected [Hash] the ruleset as `Tools::Lanes` projects it
+      # @return [Symbol] `:created` or `:updated`
+      # @raise [RuntimeError] when GitHub refuses it
+      def apply(projected)
+        live = named(projected.fetch("name"))
+        path = "repos/{owner}/{repo}/rulesets"
+        if live
+          call("api", "--method", "PUT", "#{path}/#{live.fetch("id")}", "--input", "-", stdin: JSON.generate(projected))
+          :updated
+        else
+          call("api", "--method", "POST", path, "--input", "-", stdin: JSON.generate(projected))
+          :created
+        end
+      end
+
+      # How a live ruleset differs from a projected one, over the parts a lane projects.
+      #
+      # @param projected [Hash] the ruleset as `Tools::Lanes` projects it
+      # @param live [Hash, nil] the ruleset GitHub holds, or nil when it has none
+      # @return [Array<String>] one line for each difference; empty when they agree
+      def differences(projected, live)
+        return ["#{projected["name"]}: GitHub has no such ruleset"] unless live
+
+        found = COMPARED.reject { |key| projected[key] == live[key] }.map do |key|
+          "#{projected["name"]}: #{key} is #{live[key].inspect} on GitHub, #{projected[key].inspect} in the model"
+        end
+        found + %i[compare_conditions compare_bypass compare_rules compare_checks].flat_map do |part|
+          send(part, projected, live)
+        end
+      end
+
+      private
+
+      def compare_conditions(projected, live)
+        mine = projected.dig("conditions", "ref_name", "include")
+        theirs = live.dig("conditions", "ref_name", "include")
+        mine == theirs ? [] : ["#{projected["name"]}: it guards #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      def compare_bypass(projected, live)
+        mine = actors(projected)
+        theirs = actors(live)
+        return [] if mine == theirs
+
+        ["#{projected["name"]}: bypass actors are #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      def compare_rules(projected, live)
+        mine = projected.fetch("rules").map { |rule| rule["type"] }.sort
+        theirs = live.fetch("rules", []).map { |rule| rule["type"] }.sort
+        mine == theirs ? [] : ["#{projected["name"]}: rules are #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      def compare_checks(projected, live)
+        mine = contexts(projected)
+        theirs = contexts(live)
+        return [] if mine == theirs
+
+        ["#{projected["name"]}: required checks are #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      # The check names a ruleset's `required_status_checks` rule demands, sorted.
+      def contexts(ruleset)
+        rule = Array(ruleset["rules"]).find { |candidate| candidate["type"] == "required_status_checks" }
+        Array(rule&.dig("parameters", "required_status_checks")).map { |check| check["context"] }.sort
+      end
+
+      def actors(ruleset)
+        Array(ruleset["bypass_actors"]).map { |actor| actor.values_at("actor_id", "actor_type", "bypass_mode") }.sort_by(&:to_s)
+      end
+
+      def call(*args, stdin: nil)
+        out, err, ok = @runner.call(args, stdin)
+        raise "gh #{args.first(3).join(" ")} failed: #{err.strip.empty? ? out.strip : err.strip}" unless ok
+
+        out
+      end
+
+      def json(text) = JSON.parse(text)
+
+      def run_gh(args, stdin)
+        out, err, status = Open3.capture3("gh", *args, stdin_data: stdin.to_s)
+        [out, err, status.success?]
+      rescue Errno::ENOENT
+        ["", "gh is not installed or not on PATH", false]
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/host_http.rb

@@ -28,11 +28,8 @@ module Hecks
       # @raise [ArgumentError] if the path or the secret is missing, or the scheme is unknown
       # @raise [ConsoleCapture::Failure] when any check failed
       def probe(**held)
-        options = %i[url path header scheme payload health_path state_path].to_h { |name| [name, plain(held[name])] }
-        options[:payload] ||= File.read(plain(held[:payload_file])) if plain(held[:payload_file])
-
         out = StringIO.new
-        status = CLI::SmokeHttp.new(CLI::SmokeHttp.resolve(options.compact, ENV), out: out).run
+        status = CLI::SmokeHttp.new(CLI::SmokeHttp.resolve(probe_options(held).compact, ENV), out: out).run
         raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
         { output: { value: out.string } }
@@ -50,8 +47,8 @@ module Hecks
       # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
       # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
       def fetch(**held)
-        file = plain(held[:expected]) or raise ArgumentError, "no allow-list file to compare the era with"
-        timeout = plain(held[:timeout]) or raise ArgumentError, "no timeout to wait for the host with"
+        file = required(held[:expected], "no allow-list file to compare the era with")
+        timeout = required(held[:timeout], "no timeout to wait for the host with")
         finding = CLI::CheckEra.assess(plain(held[:host]), file, timeout: timeout.to_f)
 
         { era: { value: finding.verdict.era }, version: { value: finding.version },
@@ -60,6 +57,19 @@ module Hecks
 
       private
 
+      # The options the smoke check reads, from the record's fields; the payload file stands in
+      # for a payload that was not given.
+      def probe_options(held)
+        options = %i[url path header scheme payload health_path state_path].to_h { |name| [name, plain(held[name])] }
+        options[:payload] ||= File.read(plain(held[:payload_file])) if plain(held[:payload_file])
+        options
+      end
+
+      # The field's value, or an `ArgumentError` saying what is missing.
+      def required(argument, message)
+        plain(argument) or raise ArgumentError, message
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end

data/lib/hecks/hecks/adapters/in_process_boot.rb

@@ -150,15 +150,19 @@ module Hecks
         steps ||= 30
         generated = Fuzzing::SequenceGenerator.generate(target, seed: seed, steps: steps,
                                                                 adversarial: adversarial || 0.0)
-        script = { name:  "#{File.basename(target)}-generated",
-                   note:  "generated by hecks generate_sequence: seed #{seed}, #{steps} steps " \
-                          "requested (#{generated.length} produced)",
-                   steps: generated }
-        report(JSON.pretty_generate(script))
+        report(JSON.pretty_generate(sequence_script(target, generated, seed, steps)))
       end
 
       private
 
+      # The replayable script for a generated sequence: its name, how it was made, its steps.
+      def sequence_script(target, generated, seed, steps)
+        { name:  "#{File.basename(target)}-generated",
+          note:  "generated by hecks generate_sequence: seed #{seed}, #{steps} steps " \
+                 "requested (#{generated.length} produced)",
+          steps: generated }
+      end
+
       # A value object arrives as `{ value: x }`; a bare argument is already plain.
       def plain(argument)
         argument.is_a?(Hash) ? argument[:value] : argument

data/lib/hecks/hecks/adapters/in_process_operations/tailing.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module InProcessOperations
+      # The loop behind `stream`: drains an event log past a cursor, then waits and drains again,
+      # until the block, a limit or a deadline ends it.
+      module Tailing
+        # Where a stream stands: log entries seen, entries handed over, whether a batch ended it.
+        Tail = Struct.new(:seen, :handed, :batch_done)
+
+        # What ends a stream and what it follows: the aggregate filter, the most entries to hand
+        # over, the monotonic time to give up at, and the seconds between checks.
+        Bounds = Struct.new(:aggregate, :cap, :deadline, :interval)
+
+        private
+
+        # The monotonic time `timeout` seconds from now, or nil when there is no timeout.
+        def deadline_for(timeout) = plain(timeout) && (monotonic + plain(timeout).to_f)
+
+        # Drains the log, then waits and drains again, until something ends the stream.
+        #
+        # @return [Integer] the count of log entries seen
+        def watch(repository, tail, bounds, &)
+          loop do
+            verdict = drain(repository, tail, bounds.aggregate, bounds.cap, &)
+            return tail.seen if verdict == :stop || tail.batch_done || expired?(bounds.deadline)
+
+            sleep((bounds.interval || 0.5).to_f)
+          end
+        end
+
+        # Whether the stream's deadline, when it has one, has passed.
+        def expired?(deadline) = deadline && monotonic >= deadline
+
+        # Hands over what the log holds past the tail, one entry at a time; answers `:stop` when the
+        # block or the limit ends the stream, so the tail's `seen` stays just past the last entry
+        # handed over.
+        def drain(repository, tail, filter, cap)
+          events = repository.events
+          while tail.seen < events.size
+            event = events[tail.seen]
+            tail.seen += 1
+            next unless followed?(event, filter)
+
+            return :stop if handed_over?(tail, yield(JSON.parse(JSON.generate(event.to_h))), cap)
+          end
+          nil
+        end
+
+        # Records that an entry was handed over, and whether its verdict or the limit ends the
+        # stream.
+        def handed_over?(tail, verdict, cap)
+          tail.handed += 1
+          tail.batch_done ||= verdict == :batch
+          verdict == :stop || (cap && tail.handed >= cap)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/in_process_operations.rb

@@ -3,6 +3,7 @@
 require "json"
 require "time"
 require_relative "console_capture"
+require_relative "in_process_operations/tailing"
 require "hecks/cli/run"
 require "hecks/cli/model_check"
 require "hecks/cli/smoke_test"
@@ -19,10 +20,15 @@ module Hecks
     # it printed. An answer records a success; a raise records a refusal, so a check that finds
     # something, or a run that fails, is refused with the report as its reason.
     module InProcessOperations
+      include Tailing
+
       # The chapters `hecks model_check` sweep when no domain is named need a
       # checkout; an installed gem has none.
       CHECKOUT_MARKER = "hecks.gemspec"
 
+      # The line `hecks model_check` prints before each domain it examines.
+      REPORT_HEADER = /^── /
+
       # Longest a `Follow` query may wait for new entries, so one call cannot hold a launcher open.
       MAX_FOLLOW_WAIT = 60
 
@@ -30,20 +36,16 @@ module Hecks
       #
       # @param held [Hash] the `ModelCheckRun` record: `domains` (comma separated paths), `strict`
       #   and `profile`
-      # @return [Hash{Symbol => Hash}] `report:` the analysis as printed
+      # @return [Hash{Symbol => Hash}] `report:` the analysis as printed, `checked:` how many
+      #   domains it headed
       # @raise [ConsoleCapture::Failure] when a finding was left, or the analysis could not run
       def check(**held)
-        argv = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
-        missing = argv.reject { |domain| File.exist?(domain) }
-        raise Runtime::NotFound, "no such domain #{missing.first.inspect}" if missing.any?
-
-        argv.unshift("--strict") if plain(held[:strict])
-        argv.unshift("--profile", plain(held[:profile]).to_s) if present?(held[:profile])
+        argv = check_argv(held)
 
         text = ConsoleCapture.answer do
           CLI::ModelCheck.call(argv, program: "hecks model_check", root: checkout_root)
         end
-        { report: { value: text } }
+        { report: { value: text }, checked: { value: text.scan(REPORT_HEADER).size } }
       end
 
       # Dispatches one verb, or executes a step list, against a domain.
@@ -93,6 +95,8 @@ module Hecks
         output(ConsoleCapture.answer { CLI::SmokeTest.call(argv, root: checkout_root || Dir.pwd) })
       end
 
+      # rubocop:disable Metrics/ParameterLists -- the keywords are the `Follow` query's declared arguments
+
       # A domain's event log past a cursor, answered once: what the stream yielded before it
       # ended. Pass the answered `cursor` back as `since` to keep tailing. `wait` bounds the stream
       # and it ends at the first entries, so a call returns as soon as there is something to say.
@@ -106,6 +110,7 @@ module Hecks
       # @return [Hash] the `Tail` row: `cursor:`, `events:` (payloads as JSON text) and `taken_at:`
       # @raise [Runtime::NotFound] if the domain cannot be found or keeps no event log
       def follow(domain:, aggregate: nil, since: nil, from_now: nil, wait: nil, interval: nil)
+        # rubocop:enable Metrics/ParameterLists
         registry = boot(domain).registry
         entries = []
         cursor = stream(domain: domain, aggregate: aggregate, since: since, from_now: from_now,
@@ -117,6 +122,8 @@ module Hecks
         { cursor: cursor, events: entries, taken_at: Time.at(Ports::Clock.now(registry)).utc.iso8601 }
       end
 
+      # rubocop:disable Metrics/ParameterLists -- the keywords are the caller-facing shape of a tail
+
       # Tails a domain's event log, handing each entry to the block as the log shows it, until
       # the block returns `:stop` (or `:batch`: after this check's entries), `limit` entries were
       # handed over, `timeout` seconds pass, or the reader goes away; unbounded, until interrupted.
@@ -130,43 +137,38 @@ module Hecks
       # @return [Integer] the count of log entries seen, to pass back as `since`
       # @raise [Runtime::NotFound] if the domain cannot be found or keeps no event log
       def stream(domain:, aggregate: nil, since: nil, from_now: nil, limit: nil, timeout: nil, interval: nil,
-                 registry: nil, &block)
+                 registry: nil, &)
+        # rubocop:enable Metrics/ParameterLists
         repository = event_repository(domain, registry)
         tail = Tail.new(plain(since)&.to_i || (plain(from_now) ? repository.events.size : 0), 0, false)
-        cap = plain(limit)&.to_i
-        deadline = plain(timeout) && (monotonic + plain(timeout).to_f)
-
-        loop do
-          verdict = drain(repository, tail, plain(aggregate), cap, &block)
-          return tail.seen if verdict == :stop || tail.batch_done || (deadline && monotonic >= deadline)
-
-          sleep((plain(interval) || 0.5).to_f)
-        end
+        bounds = Bounds.new(plain(aggregate), plain(limit)&.to_i, deadline_for(timeout), plain(interval))
+        watch(repository, tail, bounds, &)
       rescue Errno::EPIPE, Interrupt
         tail.seen
       end
 
       private
 
-      # Where a stream stands: log entries seen, entries handed over, whether a batch ended it.
-      Tail = Struct.new(:seen, :handed, :batch_done)
-
-      # Hands over what the log holds past the tail, one entry at a time; answers `:stop` when the
-      # block or the limit ends the stream, so the tail's `seen` stays just past the last entry
-      # handed over.
-      def drain(repository, tail, filter, cap)
-        events = repository.events
-        while tail.seen < events.size
-          event = events[tail.seen]
-          tail.seen += 1
-          next unless followed?(event, filter)
-
-          verdict = yield JSON.parse(JSON.generate(event.to_h))
-          tail.handed += 1
-          tail.batch_done ||= verdict == :batch
-          return :stop if verdict == :stop || (cap && tail.handed >= cap)
-        end
-        nil
+      # The words `hecks model_check` is run with: the named domains, behind `--strict` and
+      # `--profile` when asked for.
+      #
+      # @raise [Runtime::NotFound] if a named domain does not exist
+      def check_argv(held)
+        argv = named_domains(held)
+        argv.unshift("--strict") if plain(held[:strict])
+        argv.unshift("--profile", plain(held[:profile]).to_s) if present?(held[:profile])
+        argv
+      end
+
+      # The domain paths the record names, each of which must exist.
+      #
+      # @raise [Runtime::NotFound] if one does not
+      def named_domains(held)
+        argv = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
+        missing = argv.reject { |domain| File.exist?(domain) }
+        raise Runtime::NotFound, "no such domain #{missing.first.inspect}" if missing.any?
+
+        argv
       end
 
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)

data/lib/hecks/hecks/adapters/journal_store/changes.rb

@@ -55,7 +55,7 @@ module Hecks
           diverged = domain.writing { |lineage| diverged_writes(domain, lineage) }
           PostgresEra::LineageManager.merge!(registry: domain.registry, bluebook: domain.bluebook,
                                              settings: domain.settings, winners: named)
-          ["#{domain.bluebook.name}: #{diverged} post-cut write#{'s' unless diverged == 1} in ancestor " \
+          ["#{domain.bluebook.name}: #{diverged} post-cut write#{"s" unless diverged == 1} in ancestor " \
            "eras before the merge",
            "merged — the head now interleaves both worlds by their recorded ordinals",
            *named.map { |id, side| "  winner #{id}=#{side} appended as the newest row" }].join("\n")
@@ -88,17 +88,19 @@ module Hecks
           before = missing.call
           return "#{domain.bluebook.name}: every held era already carries a projection — nothing to do." if before.zero?
 
-          begin
-            # Raises on the first row whose own digest check fails: a tampered row, not a merely
-            # legacy one, which backfilling must not paper over.
-            lineage.eras
-          rescue Runtime::WiringError => e
-            raise Runtime::WiringError, "#{domain.bluebook.name}: stopped at a row that isn't merely legacy — " \
-                                        "it fails its own integrity check: #{e.message} — resolve that first " \
-                                        "(`hecks reattest`), then run this again for the remaining rows."
-          end
+          require_legacy_rows!(domain, lineage)
           done = before - missing.call
-          "#{domain.bluebook.name}: backfilled #{done} era#{'s' unless done == 1} — every row now carries a projection."
+          "#{domain.bluebook.name}: backfilled #{done} era#{"s" unless done == 1} — every row now carries a projection."
+        end
+
+        # Raises on the first row whose own digest check fails: a tampered row, not a merely
+        # legacy one, which backfilling must not paper over.
+        def require_legacy_rows!(domain, lineage)
+          lineage.eras
+        rescue Runtime::WiringError => e
+          raise Runtime::WiringError, "#{domain.bluebook.name}: stopped at a row that isn't merely legacy — " \
+                                      "it fails its own integrity check: #{e.message} — resolve that first " \
+                                      "(`hecks reattest`), then run this again for the remaining rows."
         end
 
         def missing_projections(lineage)
@@ -120,13 +122,17 @@ module Hecks
         def apply_approve_translation(held)
           domain = HeldDomain.open(plain(held[:domain]))
           finding = domain.reading { |lineage| audited_edge(domain, lineage) }
-          document = Translation::ApprovalFile.build(
+          document = approval_document(domain, finding, held)
+          path = Translation::ApprovalFile.write!(domain.directory, finding.edge, document)
+          "approval of edge #{document["edge"]} written to #{path} (digest #{document["edge_digest"][0, 12]}…, " \
+            "by #{document["approved_by"]}). Commit it with the edge; the host applies it at its next boot."
+        end
+
+        def approval_document(domain, finding, held)
+          Translation::ApprovalFile.build(
             edge: finding.edge, approved_by: Git.new.identity(chdir: domain.directory),
             approved_at: Time.now.utc.iso8601, rehearsal: rehearsal_block(held)
           )
-          path = Translation::ApprovalFile.write!(domain.directory, finding.edge, document)
-          "approval of edge #{document['edge']} written to #{path} (digest #{document['edge_digest'][0, 12]}…, " \
-            "by #{document['approved_by']}). Commit it with the edge; the host applies it at its next boot."
         end
 
         def audited_edge(domain, lineage)