hecks 2.8.0 → 3.0.0

data/lib/hecks/cli/project_cli.rb

@@ -3,58 +3,135 @@ require_relative "../../hecks"
 
 module Hecks
   module CLI
-    # The command behind `bin/project_cli` and `hecks project_cli`: writes a
+    # The command behind `hecks project_cli` and `hecks project_cli`: writes a
     # command-line launcher beside each domain, named after its bluebook, so
     # `Hecks.bluebook "QualityControl"` in `qa/` becomes `qa/quality_control`.
     #
-    # ## A launcher, not a CLI
+    # Each launcher is a dozen lines pinning one directory and handing over to
+    # `Doors::CliRunner`; the surface itself is projected at the moment it runs,
+    # so editing a chapter changes behaviour without regenerating anything.
     #
-    # Each file is a dozen lines pinning one directory and handing over to
-    # `Facade::CliRunner`. The surface still comes from `Projector.call(:cli, …)` at
-    # the moment it runs, so editing a chapter changes the launcher's behaviour
-    # without regenerating anything. Re-run this when a domain is added or renamed.
-    #
-    # ## Beside the domain
-    #
-    # A domain's command line lives with the domain, so a folder is the whole unit.
-    # The launcher boots `__dir__`, and reaches `lib` by counting how deep the domain
-    # sits below the root, so no line knows where the checkout was cloned.
+    # A chapter whose world's `launcher` setting names an `executable` gets its launcher
+    # there instead: the Hecks chapter's is the gem's `exe/hecks`.
     module ProjectCli
       # Build output and other trees under a root that hold no domain a caller means.
       IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
 
+      # What a chapter name, a domain path and a launcher verb may be made of.
+      NAME = /\A[A-Za-z][A-Za-z0-9_ ]*\z/
+      PATH = %r{\A[\w./-]+\z}
+      VERB = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+      # Set first in an opted-in launcher, before anything reads a file.
+      ENCODING = "Encoding.default_external = Encoding::UTF_8\nEncoding.default_internal = Encoding::UTF_8\n\n".freeze
+
+      # How every launcher ends.
+      PLAIN_ENDING = "status.zero? ? puts(text) : abort(text)".freeze
+
+      # How an opted-in launcher ends: a failed `--wait` run still prints its settled record.
+      OPTED_ENDING = <<~LAUNCHER_TAIL.chomp.freeze
+        # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
+        # either way, and says why on stderr.
+        if reason
+          puts text
+          warn reason
+          exit status
+        end
+        status.zero? ? puts(text) : abort(text)
+      LAUNCHER_TAIL
+
+      # The generator's name as an executable launcher's header states it, whoever ran it.
+      GENERATOR = "hecks project_cli".freeze
+
       module_function
 
-      # Writes a launcher for each domain `argv` names, or for every domain under
-      # `root`.
+      # Writes a launcher for each named domain, or for every domain under `root`.
       #
-      # @param argv [Array<String>] domain paths relative to `root`; empty for all of them
-      # @param program [String] the name the generated header credits
-      # @param root [String] the directory domains are found under and paths resolve against
-      # @param remove_stale_bin [Boolean] whether to delete `root/bin/<name>`, where a
-      #   launcher for the same chapter would otherwise linger as a second front door
+      # `--check` writes nothing and exits 1 when a launcher differs from the one this would
+      # write. A domain that cannot boot has none to compare, so it fails too.
+      #
+      # @param argv [Array<String>] domain paths under `root`, and optionally `--check`
+      # @param program [String] how the caller was invoked, named in a launcher's header
+      # @param root [String] the directory launchers are written under
+      # @param remove_stale_bin [Boolean] delete `root/bin/<name>`, a second front door
       # @return [void]
+      # @raise [SystemExit] with status 1 for a launcher out of date, an unreadable domain, a
+      #   path outside `root` or an unknown flag
       def call(argv, program:, root:, remove_stale_bin: true)
-        wanted = argv.empty? ? domains(root) : argv.map { |path| path.delete_prefix("#{root}/").chomp("/") }
+        flags, paths = argv.partition { |word| word.start_with?("-") }
+        unknown = flags - ["--check"]
+        abort "hecks project_cli: unknown option #{unknown.first} (the only option is --check)" unless unknown.empty?
 
-        wanted.each do |path|
-          name  = bluebook_name(root, path) or next
-          snake = Naming.snake(name)
-          file  = File.join(root, path, snake)
+        check  = flags.include?("--check")
+        wanted = paths.empty? ? domains(root) : paths.map { |path| under_root(root, path) }
 
-          File.write(file, launcher(path, name, program))
-          FileUtils.chmod("+x", file)
-          FileUtils.rm_f(File.join(root, "bin", snake)) if remove_stale_bin
+        outcomes = wanted.to_h { |path| [path, one(root, path, program, check, remove_stale_bin)] }
+        drifted  = outcomes.select { |_, outcome| outcome == :drifted }.keys
+        failed   = outcomes.select { |_, outcome| outcome == :failed }.keys
+        return if drifted.empty? && failed.empty?
 
-          puts "  #{path}/#{snake}  ->  #{name}"
-        end
+        warn "launcher out of date for: #{drifted.join(', ')}; run `hecks project_cli #{drifted.join(' ')}`" unless drifted.empty?
+        warn "no launcher could be checked or written for: #{failed.join(', ')}" unless failed.empty?
+        exit 1
       end
 
-      # Finds every domain under `root` a launcher can be written for.
+      # A domain path as a path under `root`.
       #
-      # @param root [String] the directory to search under
-      # @return [Array<String>] domain directory paths relative to `root`,
-      #   deduplicated and sorted
+      # @param root [String] the directory launchers are written under
+      # @param path [String] the path as typed, relative to `root` or absolute
+      # @return [String] the path relative to `root`
+      # @raise [SystemExit] when the path is outside `root`
+      def under_root(root, path)
+        expanded = File.expand_path(path, root)
+        inside   = expanded == root || expanded.start_with?("#{root}/")
+        abort "hecks project_cli: #{path.inspect} is outside #{root}" unless inside
+
+        relative = expanded.delete_prefix(root).delete_prefix("/")
+        relative.empty? ? "." : relative
+      end
+
+      # @api private
+      # @return [Symbol] `:current` when the launcher is (or was made) as generated, `:drifted`
+      #   when `check` found it out of date, `:failed` when the domain could not be read or its
+      #   launcher could not be made
+      def one(root, path, program, check, remove_stale_bin)
+        runtime = Hecks.boot(File.join(root, path), install_doors: false)
+        name    = runtime.registry.bluebooks.keys.first or raise "it loads no bluebook"
+        setting    = Doors::LauncherOptions.settings(runtime, name) || {}
+        snake      = Naming.snake(name)
+        executable = setting[:executable]
+        label      = executable || "#{path}/#{snake}"
+        file       = File.join(root, label)
+        text       = launcher(path, name, program, executable: executable, legacy: setting[:legacy],
+                          opted: !setting.empty?)
+        return skip(path, "#{label} is a directory") if File.directory?(file)
+
+        return :drifted if check && !(File.file?(file) && File.read(file) == text)
+
+        unless check
+          File.write(file, text)
+          FileUtils.chmod("+x", file)
+          FileUtils.rm_f(File.join(root, "bin", snake)) if remove_stale_bin && !executable
+        end
+        puts "  #{label}  ->  #{name}"
+        :current
+      rescue StandardError => e
+        refuse(path, "cannot boot — #{e.message.lines.first.to_s.strip}")
+      end
+
+      # @api private
+      # @return [Symbol] `:current`: a directory where the launcher would go has nothing to check
+      def skip(path, reason)
+        warn "  #{path}: #{reason}; no launcher written"
+        :current
+      end
+
+      # @api private
+      def refuse(path, reason)
+        warn "  #{path}: #{reason}"
+        :failed
+      end
+
       def domains(root)
         folder = Adapters::Folder.new
         Dir.glob(File.join(root, "**/*.hecksagon"))
@@ -65,30 +142,41 @@ module Hecks
            .uniq.sort
       end
 
-      # Boots the domain to read its declared name, which comes from
-      # `Hecks.bluebook "…"` rather than the directory, so a domain renamed with
-      # `formerly_known_as` gets a launcher under its new name.
-      #
-      # @param root [String] the directory `path` is relative to
-      # @param path [String] a domain directory path
-      # @return [String, nil] the domain's declared bluebook name, or nil after warning
-      #   when it fails to boot
-      def bluebook_name(root, path)
-        Hecks.boot(File.join(root, path), install_facade: false).registry.bluebooks.keys.first
-      rescue StandardError => e
-        warn "  #{path}: cannot boot — #{e.message.lines.first.strip}"
-        nil
-      end
-
-      # Renders one domain's launcher.
-      #
-      # @param path [String] the domain directory path, relative to the root
-      # @param name [String] the domain's declared bluebook name
-      # @param program [String] the name the generated header credits
-      # @return [String] the launcher script's full source
-      def launcher(path, name, program)
+      # The source of one launcher; names and paths go in as they are, so each must be plain.
+      # An `opted` one also sets UTF-8 and prints a failed `--wait` record on stdout.
+      # @param path [String] the domain's directory under the root
+      # @param name [String] the chapter's name
+      # @param program [String] the generator's invocation, named in the header
+      # @param executable [String, nil] the file's path under the root when it is not beside the
+      #   domain; its program name is then that file's basename, and its header names the generator
+      # @param legacy [Array<String>, nil] verbs an executable hands to `Hecks::CLI` first
+      # @param opted [Boolean] whether the chapter's world declares a `launcher` setting
+      # @return [String] the Ruby source
+      # @raise [ArgumentError] if a name, path, executable or legacy verb is not plain
+      def launcher(path, name, program, executable: nil, legacy: nil, opted: !executable.nil?)
+        plain!("chapter name", name, NAME)
+        plain!("domain path", path, PATH)
         snake = Naming.snake(name)
-        up    = "../" * path.count("/").succ
+        if executable
+          plain!("launcher executable", executable, PATH)
+          if executable.split("/").include?("..")
+            raise ArgumentError, "launcher executable #{executable.inspect} must stay inside the root"
+          end
+
+          up      = "../" * File.dirname(executable).split("/").reject { |part| part == "." }.length
+          boot    = %(File.expand_path("#{up}#{path}", __dir__))
+          program = GENERATOR
+          where   = executable
+          shown   = File.basename(executable)
+        else
+          up    = "../" * path.count("/").succ
+          boot  = "__dir__"
+          where = shown = "#{path}/#{snake}"
+        end
+
+        handoff  = legacy_handoff(Array(legacy)) if executable
+        encoding = opted ? ENCODING : ""
+        ending   = opted ? OPTED_ENDING : PLAIN_ENDING
 
         <<~RUBY
           #!/usr/bin/env ruby
@@ -99,23 +187,94 @@ module Hecks
           # projected from the bluebook beside it every time this runs, so a change
           # to the chapter shows up here without re-minting anything.
           #
-          #   #{path}/#{snake}                  every verb, and every question
-          #   #{path}/#{snake} <verb> --help    what it wants, and how it refuses
-
-          $LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
+          #   #{where}                  every verb, and every question
+          #   #{where} <verb> --help    what it wants, and how it refuses
 
+          #{encoding}$LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
+          #{handoff}
           require "hecks"
 
+          #{entry(name, boot, shown, opted)}
+          #{ending}
+        RUBY
+      end
+
+      # @api private
+      # @return [String] the launcher's middle: for an opted-in launcher, usage answered from the
+      #   projection and a boot only for a line that runs a verb; for any other, the boot and
+      #   dispatch every launcher has always had, byte for byte
+      def entry(name, boot, shown, opted)
+        opted ? described_entry(name, boot, shown) : plain_entry(name, boot, shown)
+      end
+
+      # @api private
+      # @return [String] the opted-in launcher's middle
+      def described_entry(name, boot, shown)
+        <<~RUBY.chomp
+          # Usage is answered from the projected chapter alone: no adapter is bound and no
+          # database is opened. Only a line that runs a verb boots the domain.
+          domain = #{boot}
+          program = "#{shown}"
+          described = begin
+            Hecks.describe(domain)
+          rescue StandardError => e
+            abort "cannot open #{name}: \#{e.message.lines.first.strip}"
+          end
+
+          text, status, reason = Hecks::Doors::CliRunner.usage(
+            runtime: described, argv: ARGV, program: program
+          )
+          unless text
+            runtime = begin
+              Hecks.boot(domain, install_doors: false)
+            rescue StandardError => e
+              abort "cannot open #{name}: \#{e.message.lines.first.strip}"
+            end
+            text, status, reason = Hecks::Doors::CliRunner.call(
+              runtime: runtime, argv: ARGV, program: program
+            )
+          end
+        RUBY
+      end
+
+      # @api private
+      # @return [String] the middle every launcher had before opted-in ones answered usage alone
+      def plain_entry(name, boot, shown)
+        <<~RUBY.chomp
           runtime = begin
-            Hecks.boot(__dir__, install_facade: false)
+            Hecks.boot(#{boot}, install_doors: false)
           rescue StandardError => e
             abort "cannot open #{name}: \#{e.message.lines.first.strip}"
           end
 
-          text, status = Hecks::Facade::CliRunner.call(
-            runtime: runtime, argv: ARGV, program: "#{path}/#{snake}"
+          text, status = Hecks::Doors::CliRunner.call(
+            runtime: runtime, argv: ARGV, program: "#{shown}"
           )
-          status.zero? ? puts(text) : abort(text)
+        RUBY
+      end
+
+      # @api private
+      def plain!(what, value, pattern)
+        return if value.to_s.match?(pattern)
+
+        raise ArgumentError, "#{what} #{value.to_s.inspect} is not a plain word or path"
+      end
+
+      # @api private
+      # @return [String] the lines that hand the legacy verbs to `Hecks::CLI`, or nothing
+      def legacy_handoff(legacy)
+        return "" if legacy.empty?
+
+        legacy.each { |verb| plain!("legacy verb", verb, VERB) }
+
+        <<~RUBY
+
+          # The names the gem has always shipped keep their positional forms.
+          LEGACY = %w[#{legacy.join(' ')}].freeze
+          if LEGACY.include?(ARGV.first)
+            require "hecks/cli"
+            exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
+          end
         RUBY
       end
     end

data/lib/hecks/cli/project_diagrams.rb

@@ -2,27 +2,21 @@ require_relative "../../hecks"
 
 module Hecks
   module CLI
-    # The command behind `bin/project_diagrams` and `hecks project_diagrams`: boots a
+    # The command behind `hecks project_diagrams`: boots a
     # domain, finds the chapter it names, and writes its Mermaid diagrams
     # (`Projections::Diagrams`) under `docs/generated/diagrams/<chapter>/` below the
-    # root.
+    # root. Only this positional form writes; the launcher's `domain=… chapter=…` question
+    # prints the same files' text and writes nothing.
     module ProjectDiagrams
       module_function
 
-      # Projects and writes one chapter's diagrams, then lists what was written.
-      #
-      # @param argv [Array<String>] the domain path, then the chapter name
-      # @param program [String] the name the usage message calls this command by
-      # @param root [String] the directory `docs/generated/diagrams/` is written under
-      # @return [void]
-      # @raise [SystemExit] when either argument is missing
       def call(argv, program:, root:)
         usage = "usage: #{program} <domain-path> <ChapterName>"
         domain_path  = argv[0] or abort usage
         chapter_name = argv[1] or abort usage
 
         runtime   = Hecks.boot(File.expand_path(domain_path, Dir.pwd))
-        chapter   = runtime.registry.bluebook(chapter_name)
+        chapter   = runtime.registry.bluebook(chapter_name) or abort "no chapter named #{chapter_name}"
         hecksagon = runtime.registry.hecksagon(chapter_name)
         directory = File.expand_path("docs/generated/diagrams/#{Naming.snake(chapter_name)}", root)
 

data/lib/hecks/cli/project_glossary.rb

@@ -0,0 +1,44 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `hecks glossary`: boots a domain and projects one chapter into its
+    # Ubiquitous Language glossary, `glossary.md` plus `html/index.html` rendered from it, in the
+    # domain's own `glossary/` folder.
+    #
+    # A field the deployment marks sensitive (`has_phi(readable_by:)` in the domain's `.hecksagon`)
+    # is tagged in the glossary with its category. spec/glossary_spec.rb re-projects every one and
+    # refuses a diff, so a committed glossary never lags the bluebook it describes.
+    module ProjectGlossary
+      module_function
+
+      # Writes the chapter's glossary and prints each file written.
+      #
+      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param program [String] the name the usage line shows
+      # @return [void]
+      # @raise [SystemExit] with the usage line when an argument is missing
+      def call(argv, program: "hecks glossary")
+        usage = "usage: #{program} <domain-path> <ChapterName>"
+        domain_path  = argv[0] or abort usage
+        chapter_name = argv[1] or abort usage
+
+        domain  = File.expand_path(domain_path, Dir.pwd)
+        runtime = Hecks.boot(domain)
+        chapter = runtime.registry.bluebook(chapter_name)
+
+        markings = runtime.registry.pending_privacy_markings.select do |marking|
+          marking[:domain].to_s.start_with?("#{chapter_name}::")
+        end
+
+        written = Projector.write(
+          Projector.call(:glossary, bluebook: chapter, options: { markings: markings }),
+          File.join(domain, "glossary"), as: :files
+        )
+
+        puts "wrote #{written.size} file(s):"
+        written.each { |path| puts "  #{path}" }
+      end
+    end
+  end
+end

data/lib/hecks/cli/reference.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks"
+require_relative "../projection_files"
+
+module Hecks
+  module CLI
+    # The command behind `hecks project_reference`: regenerates `docs/implemented/reference/` from
+    # the language's Syntax chapter. Tables come from the declaration; prose is kept from the
+    # committed pages.
+    module Reference
+      module_function
+
+      # Writes the pages and reports both coverage gates together (`DocCoverage` asks the same
+      # as an exit status).
+      #
+      # @param root [String] the repository root
+      # @param out [IO] where the report goes
+      # @return [Integer] the exit status, always 0
+      def call(root:, out: $stdout)
+        directory = File.join(root, "docs/implemented/reference")
+        written = Hecks::ProjectionFiles.write(:reference, root: root)
+        out.puts "wrote #{written.size - 1} pages to docs/implemented/reference/, " \
+                 "and regenerated README.md's own indexes"
+        { "prose"             => Hecks::Doc::Reference.undocumented(directory),
+          "a running example" => Hecks::Doc::Reference.unexemplified(directory) }.each do |owed, missing|
+          report(out, owed, missing)
+        end
+        0
+      end
+
+      # @param out [IO] where the line goes
+      # @param owed [String] what each word owes: prose, or a running example
+      # @param missing [Array<String>] the words that lack it
+      # @return [void]
+      def report(out, owed, missing)
+        if missing.empty?
+          out.puts "every live word carries #{owed}."
+        else
+          out.puts "#{missing.size} word(s) still carry no #{owed}:"
+          missing.each { |word| out.puts "  #{word}" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/refresh_projections.rb

@@ -0,0 +1,44 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The logic behind `hecks refresh_projections` and Custodian's `Operation.RefreshProjections`:
+    # forces every
+    # read-model projection a booted domain declares to catch up now, the same catch-up a boot
+    # runs lazily on first read.
+    module RefreshProjections
+      module_function
+
+      # Boots the domain `argv` names and refreshes its projections, as `hecks refresh_projections`
+      # does.
+      #
+      # @param argv [Array<String>] the domain directory, first
+      # @param program [String] the name the usage message calls this command by
+      # @return [Integer] 0
+      # @raise [SystemExit] when `argv` is empty
+      def run(argv, program: "hecks refresh_projections")
+        domain = argv.first or abort "usage: #{program} <domain>"
+        call(Hecks.boot(domain))
+        0
+      end
+
+      # Refreshes every projection of every chapter in a booted runtime.
+      #
+      # @param runtime [Runtime] a booted domain
+      # @return [Integer] how many projections were caught up
+      def call(runtime)
+        refreshed = 0
+        runtime.registry.bluebooks.each do |domain, bluebook|
+          bluebook.aggregates.each do |aggregate|
+            worker = Ports::Projection.worker(runtime.registry, domain, aggregate, policy: :refresh)
+            next unless worker
+
+            worker.catch_up!
+            refreshed += 1
+          end
+        end
+        refreshed
+      end
+    end
+  end
+end

data/lib/hecks/cli/refresh_rspec_runtime_baseline.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "open3"
+require "yaml"
+
+module Hecks
+  module CLI
+    # The command behind `hecks refresh_runtime_baseline`: regenerates the committed runtime
+    # baselines the sharded CI jobs group from. It prefers one CI run's timings; a local run is
+    # the fallback.
+    #
+    #   hecks refresh_runtime_baseline --from-run <run-id>   # preferred: one CI run's timings
+    #   hecks refresh_runtime_baseline [workers]             # fallback: this machine only
+    #
+    # `--from-run` reads the runtime-log artifacts of a successful run and writes a family only
+    # when every leg uploaded one; a partial set would skew the split. Runner seconds differ from a
+    # laptop's, so a local baseline misses subprocess-heavy specs. The local mode refuses a red run.
+    module RefreshRspecRuntimeBaseline
+      REPO = "heckslabs/hecks"
+      USAGE = "usage: hecks refresh_runtime_baseline --from-run <run-id> | [workers]"
+
+      # Only `spec/..._spec.rb:<seconds>` lines; RSpec's "Run options" line must not be copied
+      # into a committed file. Seconds can arrive in exponent form (`9.69e-05`).
+      RUNTIME_LINE = %r{\A(?<file>spec/\S+_spec\.rb):(?<seconds>\d+(?:\.\d+)?(?:e-?\d+)?)\z}
+
+      module_function
+
+      # Refreshes the baselines from a CI run or a local run.
+      #
+      # @param argv [Array<String>] `--from-run RUN_ID`, or optionally the local worker count
+      # @param root [String] the checkout whose `.github/` baselines are rewritten
+      # @param out [IO] where what was written goes
+      # @return [Integer] the exit status, 0 once written
+      # @raise [SystemExit] when the run is unreadable or unsuccessful, the local suite is red, or
+      #   no artifact family is complete
+      def call(argv, root:, out: $stdout)
+        if argv.first == "--from-run"
+          from_run(root, argv.fetch(1) { abort USAGE }, out)
+        else
+          from_local(root, argv.fetch(0, "6"), out)
+        end
+        0
+      end
+
+      # Reads the leg counts from the workflow matrix so a resize cannot leave a stale count here.
+      #
+      # @param root [String] the checkout
+      # @return [Hash{String => Hash}] each artifact family's leg count and baseline file
+      def families(root)
+        {
+          "rspec-runtime-group"       => { legs:     matrix_legs(root, "ci-rspec.yml", "rspec_shard"),
+                                           baseline: ".github/rspec_runtime_baseline.log" },
+          "postgres-io-runtime-group" => { legs:     matrix_legs(root, "ci-postgres-io-parallel.yml",
+                                                                 "rspec_postgres_io_parallel_shard"),
+                                           baseline: ".github/postgres_io_runtime_baseline.log" }
+        }
+      end
+
+      # @param root [String] the checkout
+      # @param workflow [String] the workflow file's name
+      # @param job [String] the job whose matrix is counted
+      # @return [Integer] how many groups the job's matrix has
+      def matrix_legs(root, workflow, job)
+        YAML.load_file(File.join(root, ".github/workflows", workflow)).dig("jobs", job, "strategy", "matrix", "group").size
+      end
+
+      # @param paths [Array<String>] runtime logs
+      # @return [Array<String>] one sorted `file:seconds` line per spec file
+      def baseline_lines(paths)
+        seconds_by_file = paths.flat_map { |path| File.readlines(path) }.filter_map do |line|
+          match = RUNTIME_LINE.match(line.strip) or next
+          [match[:file], Float(match[:seconds])]
+        end.to_h
+        seconds_by_file.map { |file, seconds| format("%<file>s:%<seconds>.2f", file: file, seconds: seconds) }.sort
+      end
+
+      # @param root [String] the checkout
+      # @param relative [String] the baseline's path under the checkout
+      # @param lines [Array<String>] the baseline's lines
+      # @param out [IO] where the note goes
+      # @return [void]
+      def write_baseline(root, relative, lines, out)
+        File.write(File.join(root, relative), "#{lines.join("\n")}\n")
+        out.puts "wrote #{relative}: #{lines.size} spec files"
+      end
+
+      # @param run_id [String] the CI run's id
+      # @return [void]
+      # @raise [SystemExit] when `gh` cannot read the run or it did not succeed
+      def refuse_unless_successful!(run_id)
+        out, status = Open3.capture2("gh", "run", "view", run_id, "-R", REPO, "--json", "conclusion")
+        abort "hecks refresh_runtime_baseline: could not read run #{run_id}" unless status.success?
+
+        conclusion = JSON.parse(out)["conclusion"]
+        return if conclusion == "success"
+
+        abort "hecks refresh_runtime_baseline: run #{run_id} concluded #{conclusion.inspect} — " \
+              "refusing to write a baseline from anything but a successful run"
+      end
+
+      # @param root [String] the checkout
+      # @param run_id [String] the CI run's id
+      # @param out [IO] where what was written goes
+      # @return [void]
+      # @raise [SystemExit] when no family of artifacts is complete
+      def from_run(root, run_id, out)
+        refuse_unless_successful!(run_id)
+        dir = File.join(root, "tmp/ci-runtime-#{run_id}")
+        FileUtils.rm_rf(dir)
+
+        written = families(root).count do |prefix, family|
+          system("gh", "run", "download", run_id, "-R", REPO, "-p", "#{prefix}-*", "-D", dir,
+                 out: File::NULL, err: File::NULL)
+          logs = Dir[File.join(dir, "#{prefix}-*", "*.log")]
+          legs = logs.map { |path| File.basename(File.dirname(path)) }.uniq.size
+          if legs == family[:legs]
+            write_baseline(root, family[:baseline], baseline_lines(logs), out)
+            true
+          else
+            warn "skipping #{family[:baseline]}: run #{run_id} has #{legs} of #{family[:legs]} #{prefix}-* artifacts"
+            false
+          end
+        end
+        return unless written.zero?
+
+        abort "hecks refresh_runtime_baseline: run #{run_id} had no complete artifact family — nothing written"
+      end
+
+      # @param root [String] the checkout
+      # @param workers [String] how many `parallel_rspec` workers to time with
+      # @param out [IO] where what was written goes
+      # @return [void]
+      # @raise [SystemExit] when the local suite is red
+      def from_local(root, workers, out)
+        raw = "tmp/rspec_runtime_baseline.raw.log"
+        FileUtils.mkdir_p(File.join(root, "tmp"))
+        FileUtils.rm_f(File.join(root, raw))
+
+        formatters = "--tag ~io --tag ~fuzzing --format progress --format ParallelTests::RSpec::RuntimeLogger --out #{raw}"
+        green = system("bundle", "exec", "parallel_rspec", "spec", "-n", workers, "-o", formatters, chdir: root)
+        abort "hecks refresh_runtime_baseline: the spec run failed — not writing a baseline from a red suite" unless green
+
+        write_baseline(root, families(root).fetch("rspec-runtime-group")[:baseline],
+                       baseline_lines([File.join(root, raw)]), out)
+      end
+    end
+  end
+end