hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/codebase/spec_files/report.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Codebase
+      class SpecFiles
+        # How one file ended.
+        #
+        # @!attribute [r] file
+        #   @return [String] the spec file, as named
+        # @!attribute [r] examples
+        #   @return [Integer] how many examples ran
+        # @!attribute [r] failures
+        #   @return [Integer] how many failed
+        # @!attribute [r] failed
+        #   @return [Boolean] whether the file failed: a failed example, or a file that did not load
+        # @!attribute [r] output
+        #   @return [String] what the runner printed for the file (empty when it shared a process)
+        Ending = Struct.new(:file, :examples, :failures, :failed, :output)
+
+        # The report of several files: what failing files printed, a line for each file, the
+        # isolation, the files that failed, and the total counts as the test runner spells them.
+        class Report
+          NOTES = {
+            "process" => "isolation: process (a new process for each file)",
+            "shared"  => "isolation: shared (one process; may expose order dependence)"
+          }.freeze
+
+          # @param endings [Array<Ending>] how each file ended
+          # @param isolation [String] one of `SpecFiles::ISOLATIONS`
+          # @param printed [String, nil] what the one shared process printed
+          def initialize(endings, isolation, printed: nil)
+            @endings = endings
+            @isolation = isolation
+            @printed = printed
+          end
+
+          # @return [Boolean] whether any file failed
+          def failed? = @endings.any?(&:failed)
+
+          # @return [String] the report, ending with the total example and failure counts
+          def to_s = [@printed, *details, table, verdict, totals].compact.join("\n\n")
+
+          private
+
+          def failing = @endings.select(&:failed)
+
+          def details
+            failing.reject { |one| one.output.to_s.empty? }.map { |one| "--- #{one.file} ---\n#{one.output}" }
+          end
+
+          def table = (["files:"] + @endings.map { |one| "  #{line(one)}" }).join("\n")
+
+          def line(one)
+            "#{one.file}: #{plural(one.examples, "example")}, #{plural(one.failures, "failure")}#{"  FAILED" if one.failed}"
+          end
+
+          def verdict
+            return NOTES.fetch(@isolation) unless failed?
+
+            "#{NOTES.fetch(@isolation)}\nfailed: #{failing.map(&:file).join(" ")} (#{failing.size} of #{@endings.size} files)"
+          end
+
+          def totals = "#{plural(@endings.sum(&:examples), "example")}, #{plural(@endings.sum(&:failures), "failure")}"
+
+          def plural(count, word) = "#{count} #{word}#{"s" unless count == 1}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/spec_files/shared_run.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+require_relative "report"
+
+module Hecks
+  module Adapters
+    module Codebase
+      class SpecFiles
+        # Every file in one test-runner process; the JSON formatter says which file each example
+        # belongs to, and the runner's own message which file did not load.
+        class SharedRun
+          LOAD_ERROR = /error occurred while loading (.+?)\.?$/
+
+          # @param tree [Tree] the checkout
+          # @param runner [#outcome] runs the test runner on arguments
+          def initialize(tree, runner)
+            @tree = tree
+            @runner = runner
+          end
+
+          # @param names [Array<String>] the spec files
+          # @param options [Array<String>] the runner's filters, such as `--example x`
+          # @param env [Hash{String => String}] variables the specs read
+          # @return [Array(Array<Ending>, String)] how each file ended, and what the process printed
+          def call(names, options, env)
+            Tempfile.create(["spec-files", ".json"]) do |json|
+              args = ["--format", "documentation", "--format", "json", "--out", json.path, *options, *names]
+              status, printed = @runner.outcome(args, env: env)
+              by_file = examples_by_file(json.path)
+              endings = names.map { |name| ending(name, by_file.fetch(key(name), [])) }
+              blame_load_errors(endings, status, printed)
+              [endings, printed]
+            end
+          end
+
+          private
+
+          def examples_by_file(path)
+            JSON.parse(File.read(path)).fetch("examples", []).group_by { |entry| key(entry["file_path"].to_s) }
+          rescue JSON::ParserError, Errno::ENOENT
+            {}
+          end
+
+          # A file as the runner may spell it (relative, absolute, through a symlink), made
+          # comparable.
+          def key(path)
+            full = File.expand_path(path, @tree.root)
+            File.exist?(full) ? File.realpath(full) : full
+          end
+
+          def ending(name, examples)
+            failures = examples.count { |entry| entry["status"] == "failed" }
+            Ending.new(name, examples.size, failures, failures.positive?, "")
+          end
+
+          # A file that did not load has no examples, and the runner then runs none of the others.
+          # The runner names the file; when the run failed with no failed example and no name,
+          # every file is blamed.
+          def blame_load_errors(endings, status, printed)
+            return if status.zero? || endings.any?(&:failed)
+
+            named = loading(printed)
+            (named.empty? ? endings : endings.select { |one| named.include?(key(one.file)) }).each { |one| one.failed = true }
+          end
+
+          def loading(printed) = printed.scan(LOAD_ERROR).flatten.map { |path| key(path) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/spec_files.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "test_runner"
+require_relative "spec_files/report"
+require_relative "spec_files/shared_run"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # Several spec files run in one launcher boot, and how each ended.
+      #
+      # `process` isolation gives every file a new process of its own, so nothing one file defines,
+      # stubs or registers reaches the next: it saves the launcher's boot, not each file's load.
+      # `shared` isolation runs every file in one test-runner process, the fastest, and may expose
+      # an order dependence between files (constants, stubs, Memory registries are shared).
+      #
+      # The report names each file with its example and failure counts, and ends with the total
+      # counts as the test runner spells them. A run in which any file failed is refused with it.
+      class SpecFiles
+        # Every way the files can be isolated; the first is the default.
+        ISOLATIONS = %w[process shared].freeze
+
+        # The example filter that matches every example.
+        ALL_EXAMPLES = " "
+
+        COUNTS = /(\d+) examples?, (\d+) failures?/
+
+        # @param tree [Tree] the checkout whose specs are run
+        # @param runner [TestRunner] runs the test runner on arguments
+        def initialize(tree, runner: TestRunner.new(tree))
+          @tree = tree
+          @runner = runner
+        end
+
+        # @param files [String, Array<String>] spec files, relative to the checkout or absolute; a
+        #   string is split on whitespace
+        # @param example [String, nil] part of an example's description; every example when nil
+        # @param isolation [String] one of `ISOLATIONS`
+        # @param env [Hash{String => String}] variables the specs read, set for these runs only
+        # @param tags [String, nil] RSpec tag filters as the runner spells them
+        # @return [String] the per-file counts and the total, when every file passed
+        # @raise [ConsoleCapture::Failure] naming the files that failed, or that are not there
+        def run(files:, example: nil, isolation: "process", env: {}, tags: nil)
+          names = Array(files).flat_map { |name| name.to_s.split }.uniq
+          check(names, isolation)
+          report = isolate(isolation, names, filters(example, tags), env)
+          raise ConsoleCapture::Failure, report.to_s if report.failed?
+
+          report.to_s
+        end
+
+        private
+
+        # A single space matches every example, and a named example overrides the tag exclusions
+        # (`:io`, `:process`, `:fuzzing`) as a one-file run does, so an absent filter is that space.
+        def filters(example, tags) = ["--example", example.to_s.empty? ? ALL_EXAMPLES : example, *tags.to_s.split]
+
+        def isolate(isolation, names, options, env)
+          isolation == "shared" ? shared(names, options, env) : fresh(names, options, env)
+        end
+
+        def check(names, isolation)
+          raise ConsoleCapture::Failure, "no spec files named" if names.empty?
+          unless ISOLATIONS.include?(isolation)
+            raise ConsoleCapture::Failure, "isolation is process or shared, not #{isolation.inspect}"
+          end
+
+          missing = names.reject { |name| File.file?(File.expand_path(name, @tree.root)) }
+          raise ConsoleCapture::Failure, "no such spec file #{missing.join(" ")}" unless missing.empty?
+        end
+
+        def fresh(names, options, env)
+          endings = names.map do |name|
+            status, printed = @runner.outcome([*options, name], env: env, fresh: true)
+            examples, failures = counts(printed)
+            Ending.new(name, examples, failures, !status.zero?, printed)
+          end
+          Report.new(endings, "process")
+        end
+
+        def shared(names, options, env)
+          endings, printed = SharedRun.new(@tree, @runner).call(names, options, env)
+          Report.new(endings, "shared", printed: printed)
+        end
+
+        def counts(printed)
+          found = printed.match(COUNTS)
+          found ? [found[1].to_i, found[2].to_i] : [0, 0]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/test_runner.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "stringio"
+require "open3"
+require "rbconfig"
 require_relative "tree"
 require_relative "../console_capture"
 
@@ -13,6 +15,9 @@ module Hecks
       # description for a shell. What the runner prints is captured and comes back as the answer;
       # a run that fails refuses with the same text.
       class TestRunner
+        # The program a fresh process runs: the test runner, on the arguments it is handed.
+        FRESH_RUNNER = 'require "rspec/core"; exit RSpec::Core::Runner.run(ARGV)'
+
         class << self
           # @return [#call, nil] takes `(args, err, out)` and answers the exit status; the test
           #   runner when nil. A spec replaces it so no example has to run to test what is asked.
@@ -58,16 +63,60 @@ module Hecks
           report
         end
 
+        # Runs every spec in the given files or directories, from the checkout's root: a whole suite
+        # is one directory, a changed-file run is the specs those files map to.
+        #
+        # @param paths [Array<String>] spec files or directories, relative to the checkout or
+        #   absolute
+        # @param env [Hash{String => String}] variables the specs read, set for this run only
+        # @param tags [String, nil] RSpec tag filters as the runner spells them
+        # @return [String] what the runner printed when every spec it ran passed
+        # @raise [ConsoleCapture::Failure] when a path is not there, or a spec failed
+        def run_paths(paths:, env: {}, tags: nil)
+          missing = paths.reject { |path| File.exist?(File.expand_path(path, @tree.root)) }
+          raise ConsoleCapture::Failure, "no such spec #{missing.first}" unless missing.empty?
+
+          report = with_env(env) { run_args([*tags.to_s.split, *paths]) }
+          raise ConsoleCapture::Failure, "the test runner printed nothing for #{paths.join(" ")}" if report.empty?
+
+          report
+        end
+
+        # Runs the runner on the arguments and answers how it ended, whatever the result: a
+        # caller that reports each of several runs reads the status, not a refusal.
+        #
+        # @param args [Array<String>] the runner's arguments
+        # @param env [Hash{String => String}] variables the specs read, set for this run only
+        # @param fresh [Boolean] whether to run it in a new process of its own (nothing a spec
+        #   defined, stubbed or registered carries over) or in this one
+        # @return [Array(Integer, String)] the exit status and what the runner printed
+        def outcome(args, env: {}, fresh: false)
+          return with_env(env) { in_process(args) } unless fresh
+
+          printed, status = Open3.capture2e(env, RbConfig.ruby, "-e", FRESH_RUNNER, "--", *args, chdir: @tree.root)
+          [status.exitstatus || 1, printed.strip]
+        end
+
         private
 
         # What the runner printed for the example, when it passed.
         def run_example(path, example, tags = [])
+          run_args(["--example", example, *tags, path])
+        end
+
+        # What the runner printed for the arguments, when every spec it ran passed.
+        def run_args(args)
+          status, printed = in_process(args)
+          raise ConsoleCapture::Failure, printed unless status.zero?
+
+          printed
+        end
+
+        # The runner's exit status and what it printed, for the arguments, in this process.
+        def in_process(args)
           out = StringIO.new
-          args = ["--example", example, *tags, path]
           status = Dir.chdir(@tree.root) { at_reaction_depth_zero { runner.call(args, out, out) } }
-          raise ConsoleCapture::Failure, out.string.strip unless status.zero?
-
-          out.string.strip
+          [status, out.string.strip]
         end
 
         def at_reaction_depth_zero(&) = self.class.at_reaction_depth_zero(&)

data/lib/hecks/hecks/adapters/codebase/test_scope.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # How much of the spec suite this machine may run, from the world's
+      # `test_scope "Local", suite_runs_in: "ci", spec_files_limit: n` setting. Owner decision: the
+      # full suite runs only in CI (the `rspec` check is `runs_in: "ci"` in the Vocabulary rows),
+      # and a change is checked locally by the quick gate and the specs named for it, at most
+      # `spec_files_limit` files per call.
+      #
+      # CI is detected here, by the environment (`CI` or `GITHUB_ACTIONS`), never by the bluebook. A
+      # world that declares no `test_scope` (a client's project) is not limited.
+      class TestScope
+        # The world verb that carries the setting.
+        VERB = "test_scope"
+
+        # The spec files a directory holds.
+        SPEC_GLOB = "**/*_spec.rb"
+
+        # @param registry [Runtime::Registry, nil] the booted registry whose Hecks world is read
+        # @return [Hash{Symbol => Object}] the declared setting, empty when none is
+        def self.setting(registry) = registry&.world("Hecks")&.for_verb(VERB) || {}
+
+        # @param registry [Runtime::Registry, nil]
+        # @return [Integer, nil] the most spec files a local call may run, nil when none is declared
+        def self.limit(registry)
+          declared = setting(registry)[:spec_files_limit]
+          declared && Integer(declared)
+        end
+
+        # @param registry [Runtime::Registry, nil] the booted registry whose Hecks world is read
+        # @param env [#[]] the process environment
+        def initialize(registry, env: ENV)
+          @setting = self.class.setting(registry)
+          @env = env
+        end
+
+        # @return [Integer, nil] the limit that holds here: nil in CI or when none is declared
+        def limit = (Integer(@setting[:spec_files_limit]) if @setting[:spec_files_limit] && !ci?)
+
+        # @return [Boolean] whether this process runs in CI
+        def ci? = %w[CI GITHUB_ACTIONS].any? { |name| !["", "false"].include?(@env[name].to_s) }
+
+        # Lets a request through, or refuses one that would run more than this machine may. An
+        # impacted run that names no cap gets the limit as its cap.
+        #
+        # @param operation [String] the `TestSuiteRun` operation
+        # @param held [Hash] the record's fields, each perhaps a value object's `{ value: x }`
+        # @param tree [Tree] the folder whose specs would run
+        # @return [Hash] the fields to carry the operation out with
+        # @raise [ConsoleCapture::Failure] naming the limit and CI
+        def admit(operation, held, tree)
+          args = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          refuse!(operation, args, tree) unless ci?
+          return held unless operation == "run_impacted_specs" && limit && args[:cap].nil?
+
+          held.merge(cap: { value: limit })
+        end
+
+        private
+
+        def refuse!(operation, args, tree)
+          case operation
+          when "run_suite" then refuse_suite
+          when "run_spec_files" then refuse_files(files_in(args[:files], tree))
+          when "run_impacted_specs" then refuse_cap(args[:cap])
+          end
+        end
+
+        def refuse_suite
+          return unless @setting[:suite_runs_in].to_s == "ci"
+
+          fail!("the full suite runs in CI (rspec runs_in \"ci\"); run named specs, or run_impacted_specs!")
+        end
+
+        def refuse_files(count)
+          return if limit.nil? || count <= limit
+
+          fail!("run_spec_files! runs at most #{limit} spec files per call locally (spec_files_limit); #{count} named. " \
+                "The full suite runs in CI (rspec runs_in \"ci\"): name fewer files, or run_impacted_specs!")
+        end
+
+        def refuse_cap(cap)
+          return if limit.nil? || cap.nil? || Integer(cap) <= limit
+
+          fail!("run_impacted_specs! caps at #{limit} spec files locally (spec_files_limit); cap.value=#{cap} is more. " \
+                "The full suite runs in CI (rspec runs_in \"ci\")")
+        end
+
+        # A named directory counts as the spec files it holds.
+        def files_in(files, tree)
+          Array(files).flat_map { |name| name.to_s.split }.uniq.sum do |name|
+            path = File.expand_path(name, tree.root)
+            File.directory?(path) ? Dir.glob(File.join(path, SPEC_GLOB)).size : 1
+          end
+        end
+
+        def fail!(message) = raise(ConsoleCapture::Failure, message)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/test_suite.rb

@@ -2,7 +2,11 @@
 
 require "fileutils"
 require_relative "tree"
+require_relative "minitest_runs"
+require_relative "run_options"
 require_relative "test_runner"
+require_relative "changed_specs"
+require_relative "batch_runs"
 require_relative "sqlite_fixture"
 require_relative "cargo_tests"
 require_relative "cache_clearing"
@@ -13,15 +17,23 @@ module Hecks
       # What Codebase's `TestSuiteRun` asks of the working tree: the tooling around this
       # repository's specs.
       #
-      # The tooling owns its options, so each ask runs one of the `Hecks::CLI` commands in this
+      # The tooling owns its options, so each ask runs one of the `Hecks::Tools` commands in this
       # process from the checkout's root, except a single example (the `TestRunner` adapter runs it)
       # and the persistence fixtures (the `SqliteFixture` adapter). A listing is a pure read.
       # Refreshing the committed timings, regenerating the fixtures and writing the committed spec
       # list change tracked files, so unconfirmed they report what they would do and write nothing.
       module TestSuite
         # Every operation this family carries out.
-        OPERATIONS = %w[refresh_runtime_baseline run_spec_example stress_concurrency run_cargo_tests clear_caches
-                        regenerate_legacy_fixtures seed_semantics_corpus write_io_parallel_spec_list].freeze
+        OPERATIONS = %w[refresh_runtime_baseline run_spec_example run_spec_files run_impacted_specs run_suite run_changed
+                        stress_concurrency run_cargo_tests clear_caches regenerate_legacy_fixtures seed_semantics_corpus
+                        write_io_parallel_spec_list].freeze
+
+        # The operations that run specs in a folder of their own: they need that folder to hold
+        # specs, not to be this checkout, so any project's suite runs through them.
+        FOLDER_OPERATIONS = %w[run_spec_example run_spec_files run_impacted_specs run_suite run_changed].freeze
+
+        # The spec directory a folder's whole suite lives in.
+        SPEC_DIRECTORY = "spec"
 
         # The tag filter the postgres job lists its specs by when none is named.
         DEFAULT_TAGS = "--tag io --tag ~fuzzing"
@@ -31,14 +43,14 @@ module Hecks
 
         module_function
 
-        # Loads the command a `Hecks::CLI` file defines, the first time an ask needs it: several
+        # Loads the command a `Hecks::Tools` file defines, the first time an ask needs it: several
         # read the checkout's specs or need a development gem, which an installed gem lacks.
         #
-        # @param file [String] the command's file under `lib/hecks/cli/`, without the extension
+        # @param file [String] the command's file under `lib/hecks/tools/`, without the extension
         # @return [Module] the command, named as the file is, in camel case
         def command(file)
-          require "hecks/cli/#{file}"
-          Hecks::CLI.const_get(file.split("_").map(&:capitalize).join)
+          require "hecks/tools/#{file}"
+          Hecks::Tools.const_get(file.split("_").map(&:capitalize).join)
         end
 
         # Carries out one operation.
@@ -52,7 +64,9 @@ module Hecks
         def call(operation, held, tree, shell: nil)
           args = plain(held)
           case operation
-          when "run_spec_example" then spec_example(args, tree)
+          when *BatchRuns::OPERATIONS then BatchRuns.call(operation, args, tree)
+          when "run_suite" then suite(args, tree)
+          when "run_changed" then changed(args, tree)
           when "run_cargo_tests" then CargoTests.run(args, tree, shell)
           when "clear_caches" then CacheClearing.clear
           else tooling(operation, args, tree, shell)
@@ -73,30 +87,41 @@ module Hecks
           end
         end
 
-        # @param args [Hash] `file`, `example`, and the arguments that set the specs' variables
-        # @param tree [Tree] the checkout
+        # Runs every spec of the folder's spec directory in one process.
+        #
+        # @param args [Hash] `tags`, `strict`, `seeds` and `environment`, each perhaps absent
+        # @param tree [Tree] the folder whose specs run
         # @return [String] what the runner printed
-        def spec_example(args, tree)
-          TestRunner.new(tree).run(file: args[:file], example: args[:example], env: spec_env(args), tags: args[:tags])
+        def suite(args, tree)
+          rspec = TestRunner.new(tree).run_paths(paths: [SPEC_DIRECTORY], env: RunOptions.spec_env(args), tags: args[:tags])
+          minitest = MinitestRuns.files(tree)
+          return rspec if minitest.empty?
+
+          ([rspec] + MinitestRuns.reports(tree, minitest)).join("\n")
         end
 
-        # The variables the specs read, set for one example only: the arguments of the run, so a
-        # person never sets them in a shell.
+        # Runs the specs the files changed since a git ref map to, by name. Says so and runs nothing
+        # when no spec maps to a change, so an unmapped change never falls back to the whole suite.
         #
-        # @param args [Hash] `strict`, `seeds`, `environment` and `declaration_cache`, each
-        #   perhaps absent
-        # @return [Hash{String => String}] only those the run named
-        def spec_env(args)
-          { "CI" => ("true" if args[:strict] == true), "PROPERTY_SEEDS" => args[:seeds]&.to_s,
-            "HECKS_ENVIRONMENT" => args[:environment],
-            "HECKS_NO_DECLARATION_CACHE" => ("1" if args[:declaration_cache] == false) }.compact
+        # @param args [Hash] `base` (the ref, `origin/main` when absent), and the run's variables
+        # @param tree [Tree] the folder whose changes are read
+        # @return [String] what the runner printed, or that no spec maps to the changes
+        # @raise [ConsoleCapture::Failure] when git cannot read the changes
+        def changed(args, tree)
+          base = args[:base] || "origin/main"
+          files = ChangedSpecs.changed_files(tree, base)
+          specs = Dir.glob("#{SPEC_DIRECTORY}/**/*_spec.rb", base: tree.root).sort
+          mapped = ChangedSpecs.call(files, specs)
+          return "no spec maps to the #{files.size} changed file(s) since #{base}; nothing run" if mapped.empty?
+
+          TestRunner.new(tree).run_paths(paths: mapped, env: RunOptions.spec_env(args), tags: args[:tags])
         end
 
         # @param args [Hash] `runs`, `parallel` and `seed_start`
         # @param tree [Tree] the checkout
         # @return [String] what the stress run printed
         def stress(args, tree)
-          answer { command("stress_concurrency_specs").call(stress_flags(args), root: tree.root) }
+          answer { command("stress_concurrency_specs").call(RunOptions.stress_flags(args), root: tree.root) }
         end
 
         # @param args [Hash] `confirm`
@@ -115,7 +140,7 @@ module Hecks
         # @return [String] what the seeding printed
         def seed(args, tree)
           seeding = command("seed_semantics_corpus")
-          answer { TestRunner.at_reaction_depth_zero { seeding.call(root: tree.root, env: seed_env(args)) } }
+          answer { TestRunner.at_reaction_depth_zero { seeding.call(root: tree.root, env: RunOptions.seed_env(args)) } }
         end
 
         # A pure read: a listing, or the recorded pattern cases.
@@ -191,17 +216,6 @@ module Hecks
             "and rewrite #{BASELINES.join(", ")} (add --confirm)"
         end
 
-        # @param args [Hash] `runs`, `parallel` and `seed_start`
-        # @return [Array<String>] the script's flags for those that are named
-        def stress_flags(args)
-          { "--runs" => :runs, "--parallel" => :parallel, "--seed-start" => :seed_start }
-            .filter_map { |flag, name| [flag, args[name].to_s] if args[name] }.flatten
-        end
-
-        # @param args [Hash] `fixture`, perhaps absent
-        # @return [Hash{String => String}] the variable that names the one fixture to re-seed
-        def seed_env(args) = args[:fixture] ? { "SEED" => args[:fixture] } : {}
-
         # @param args [Hash] `exclude`, `tags`, `write` and `confirm`
         # @param tree [Tree] the checkout whose spec list is written
         # @return [String] what was written, or (unconfirmed) how many files would be

data/lib/hecks/hecks/adapters/console_capture.rb

@@ -6,7 +6,7 @@ require "stringio"
 module Hecks
   module Adapters
     # Runs a command-line entry point that prints and exits, and hands back what it said and how
-    # it ended, so an adapter can reuse `Hecks::CLI::*` unchanged.
+    # it ended, so an adapter can reuse `Hecks::Tools::*` unchanged.
     #
     # It is the shared base for every Custodian adapter that wraps an existing CLI: the entry
     # point keeps its own printing, `exit` and `abort`, and the adapter turns the outcome into a

data/lib/hecks/hecks/adapters/cost_explorer.rb

@@ -41,7 +41,7 @@ module Hecks
       # @raise [Error] when no complete day has passed since `since`, `aws` fails, or the
       #   rate is over the budget
       def measure(**held)
-        budget = Integer(plain(held[:budget]))
+        budget = whole_dollars(plain(held[:budget]))
         first = Date.iso8601(plain(held[:since]).to_s)
         last = today
         raise Error, "no complete day since #{first}; today (#{last}) is still being billed" if first >= last
@@ -55,6 +55,14 @@ module Hecks
 
       private
 
+      # @return [Integer] the budget as whole dollars
+      # @raise [Error] when none was given
+      def whole_dollars(budget)
+        raise Error, "no budget given: a whole number of dollars a month" if budget.nil?
+
+        Integer(budget)
+      end
+
       # @return [Date] the day the span ends before: today, in UTC
       def today = @today ? Date.iso8601(@today.to_s) : Time.now.utc.to_date
 

data/lib/hecks/hecks/adapters/dispatching/brief_text.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class Dispatching
+      # The words a session is started with, laid out from a composed brief. Every sentence in it is the
+      # Coder bluebook's; this only orders the sections, fills in the row's key and lists the areas the
+      # caller knows.
+      class BriefText
+        # The sections of a brief after the outcome, in the order they are read.
+        SECTIONS = %w[rules verification workflow landing restraints report].freeze
+
+        # @param brief [Hash] the composed brief: its attribute values by name
+        def initialize(brief)
+          @brief = brief
+        end
+
+        # @return [String] the first line of the text: the outcome
+        def first_line = "Outcome: #{plain("outcome")}"
+
+        # @param key [String] the Work row's key, which names the worktree and branch
+        # @param area [Array<String>] the areas the session may edit
+        # @param held [Array<String>] a line for each area another started row holds
+        # @param frozen [Array<String>] the areas and aggregates whose shape may not move
+        # @param limit [Integer, nil] the most spec files a session runs per call, from the world's
+        #   `test_scope` setting; fills `{limit}`
+        # @return [String] the whole text
+        def render(key, area: [], held: [], frozen: [], limit: nil)
+          parts = [first_line, labelled("Detail", plain("detail")), labelled("Area", area.join(", "))]
+          parts += SECTIONS.map { |name| plain(name) }
+          parts += [listed("coordination", held), listed("freeze", frozen)]
+          joined(parts).gsub("{work}", key).gsub("{limit}", limit&.to_s || "the world's spec_files_limit")
+        end
+
+        private
+
+        def labelled(label, text) = text.empty? ? nil : "#{label}: #{text}"
+
+        def listed(name, lines) = lines.empty? ? nil : ([plain(name)] + lines.map { |line| "- #{line}" }).join("\n")
+
+        def joined(parts) = parts.compact.reject(&:empty?).join("\n\n")
+
+        # A value is a bare string or a one-field hash, and a name is a string or a symbol.
+        def plain(name)
+          found = @brief.transform_keys(&:to_s)[name]
+          (found.is_a?(Hash) ? found.transform_keys(&:to_s)["value"] : found).to_s
+        end
+      end
+    end
+  end
+end