hecks 5.0.0 → 6.0.0

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

@@ -47,7 +47,7 @@ module Hecks
           return false if result.stderr.include?("E404")
 
           raise Release::Runner::Refusal,
-                "could not check npm for #{PACKAGE}@#{version} (#{result.stderr.strip.lines.first}); " \
+                "could not check npm for #{PACKAGE}@#{version} (#{first_error_line(result)}); " \
                 "check the network and re-run"
         end
 
@@ -85,6 +85,12 @@ module Hecks
 
         private
 
+        # The first line of what npm wrote to stderr, nil when it wrote nothing.
+        def first_error_line(result)
+          error = result.stderr.strip
+          error.lines.first
+        end
+
         def package_dir = File.join(@root, PACKAGE_DIR)
 
         def with_userconfig

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

@@ -0,0 +1,62 @@
+require_relative "corpus_tasks"
+require_relative "static_directory"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `CorpusRun` asks of the working tree to preview a static site: serve one
+      # directory of files on the loopback address only, until the server is stopped.
+      #
+      # The server hook is the one `CorpusTasks` has, so a spec replaces every server the same way.
+      module Previewing
+        # Every operation this family carries out.
+        OPERATIONS = %w[preview].freeze
+
+        # The port the preview listens on when none is named.
+        DEFAULT_PORT = 4580
+
+        # The only address the preview binds: it carries no authentication.
+        HOST = "127.0.0.1".freeze
+
+        module_function
+
+        # Serves the directory.
+        #
+        # @param operation [String] `preview`
+        # @param held [Hash] the `CorpusRun` record's fields: `port` and `directory`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused
+        # @return [String] a note that the server stopped
+        # @raise [ConsoleCapture::Failure] when the directory is not named or is not a directory
+        def call(operation, held, tree, shell: nil)
+          _ = [operation, shell, tree]
+          fields = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          root = directory(fields[:directory])
+          port = fields[:port] || DEFAULT_PORT
+          warn "previewing #{root} on http://#{HOST}:#{port}/ - no authentication; do not expose beyond localhost"
+          (CorpusTasks.web_server || method(:serve)).call(app: StaticDirectory.new(root), port: port, host: HOST)
+          "previewed on port #{port}, now stopped"
+        end
+
+        # @param app [#call] the Rack app
+        # @param port [Integer] the port
+        # @param host [String] the address to bind
+        # @return [void]
+        def serve(app:, port:, host:)
+          require "rackup"
+          Rackup::Server.start(app: app, Host: host, Port: port, server: "webrick")
+        end
+
+        # @param named [String, nil] the directory the run names
+        # @return [String] its absolute path
+        # @raise [ConsoleCapture::Failure] when it is not named or is not a directory
+        def directory(named)
+          path = File.expand_path(named.to_s)
+          return path if !named.to_s.empty? && File.directory?(path)
+
+          raise ConsoleCapture::Failure, "preview needs directory=<path> naming a directory, not #{named.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/promotion/gate.rb

@@ -7,7 +7,7 @@ module Hecks
   module Adapters
     module Codebase
       module Promotion
-        # Where every `RequiredCheck` of the Vocabulary chapter stands against one commit.
+        # Where every `RequiredCheck` of the Vocabulary bluebook stands against one commit.
         #
         # It reports and does not decide: `Accept` holds the rule that a promotion needs every check
         # green. A check that has not finished (or has not started) is told apart from one that

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "search"
+require_relative "declarations"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `ReadSource`, `Outline` and `Declaration` queries ask of the working tree:
+      # reading a file, saying what it declares, and finding where a named construct lives, so a
+      # reader never has to leave the launcher for `cat` or `sed`.
+      #
+      # A construct is found by name, not by pattern, from the scan {Declarations} keeps. The
+      # answer is a `path:from-to` range, so one `Declaration` and one `ReadSource` read exactly
+      # the block and nothing around it; `show` does both in one call.
+      module Reading
+        # The most lines `ReadSource` returns when `top` is not named.
+        DEFAULT_TOP = 200
+
+        module_function
+
+        # @param args [Hash] the query's arguments: `path`, `from`, `to`, `top`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `line: text` row per line read, then a note when `top` cut it short
+        # @raise [ConsoleCapture::Failure] when the path is not a readable text file of the checkout
+        def read(args, tree)
+          lines = File.readlines(readable(tree, args.fetch(:path)), chomp: true)
+          from, upto, shown = window(args, lines.length)
+          rows = (from..shown).map { |number| "#{number}: #{lines[number - 1]}" }
+          rows << "(#{upto - shown} more lines to #{upto}; ask from=#{shown + 1})" if shown < upto
+          rows.join("\n")
+        end
+
+        # @return [Array<Integer>] the first line, the last line asked for, and the last line shown
+        def window(args, total)
+          from = args[:from] || 1
+          upto = [args[:to] || total, total].min
+          [from, upto, [upto, from + (args[:top] || DEFAULT_TOP) - 1].min]
+        end
+
+        # @param args [Hash] the query's argument: `path`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `from-to: kind name` row per declaration, indented by nesting
+        # @raise [ConsoleCapture::Failure] when the path is not a readable text file of the checkout
+        def outline(args, tree)
+          file = args.fetch(:path)
+          found = Declarations.outline(file, File.readlines(readable(tree, file), chomp: true))
+          found.map { |entry| "#{nesting(found, entry)}#{entry.from}-#{entry.to}: #{entry.label}" }.join("\n")
+        end
+
+        # @param args [Hash] the query's arguments: `name`, `kind`, `paths`, `show`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `path:from-to: kind "Name"` row per declaration, the block's text
+        #   after each when `show` is set
+        # @raise [ConsoleCapture::Failure] when nothing by that name is declared
+        def declaration(args, tree)
+          found = matching(Declarations.entries(tree, args[:paths]), args)
+          raise ConsoleCapture::Failure, "nothing is declared as #{args[:name].inspect}" if found.empty?
+
+          found.map { |entry| args[:show] ? shown(entry, tree) : "#{entry.range}: #{entry.label}" }.join("\n\n")
+        end
+
+        # @return [String] the file's absolute path, once it is known to be one to read
+        # @raise [ConsoleCapture::Failure] when it leaves the tree, is absent, or holds binary
+        def readable(tree, file)
+          absolute = File.expand_path(file, tree.root)
+          raise ConsoleCapture::Failure, "outside the checkout: #{file}" unless absolute.start_with?("#{tree.root}/")
+          raise ConsoleCapture::Failure, "no such file: #{file}" unless File.file?(absolute)
+          raise ConsoleCapture::Failure, "not a text file: #{file}" unless Search.text?(tree, tree.relative(absolute))
+
+          absolute
+        end
+
+        # @return [Array<Declarations::Entry>] the entries of the name (and kind, when asked)
+        def matching(entries, args)
+          entries.select { |entry| entry.name == args.fetch(:name) && [nil, entry.kind].include?(args[:kind]) }
+        end
+
+        # @return [String] two spaces for each declaration that encloses `entry`
+        def nesting(all, entry)
+          "  " * all.count { |other| other.from < entry.from && other.to >= entry.to }
+        end
+
+        def shown(entry, tree)
+          text = File.readlines(tree.path(entry.file), chomp: true)[(entry.from - 1)...entry.to]
+          body = text.each_with_index.map { |line, at| "#{entry.from + at}: #{line}" }
+          ["#{entry.range}: #{entry.label}", *body].join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -21,6 +21,9 @@ module Hecks
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
 
+        # The line the script prints before regenerating, capturing how many domains it covers.
+        REGENERATED_COUNT = /regenerating ([0-9]+) domain/
+
         module_function
 
         # Carries out the regeneration.
@@ -112,7 +115,7 @@ module Hecks
         # @param check [Boolean] whether it only compared
         # @return [String] the verdict, with how many domains it covered
         def summary(output, check)
-          count = output[/regenerating ([0-9]+) domain/, 1]
+          count = output[REGENERATED_COUNT, 1]
           return "regenerated #{count} corpus domains into the checkout" unless check
 
           "checked #{count} corpus domains against a scratch crate: no drift " \
@@ -122,7 +125,8 @@ module Hecks
         # @param result [Shell::Result] how the script ended
         # @return [String] the last lines it printed: the difference, or why it stopped
         def refusal(result)
-          lines = [result.out, result.err].join.lines.map(&:chomp).reject(&:empty?)
+          printed = [result.out, result.err].join
+          lines = printed.lines.map(&:chomp).reject(&:empty?)
           shown = lines.last(KEPT_LINES)
           note = lines.size > shown.size ? ["(the last #{shown.size} of #{lines.size} lines)"] : []
           [*note, *shown].join("\n")

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

@@ -42,7 +42,7 @@ module Hecks
         def gather(operation)
           version = declared_version
           facts = { operation: word(operation), version: word(version), client_version: word(client_version),
-                    ir_version: word("#{Bluebook::Chapter::IR_VERSION}.0.0"), ships_from: { path: @tree.root } }
+                    ir_version: word("#{Bluebook::Declaration::IR_VERSION}.0.0"), ships_from: { path: @tree.root } }
           return facts if operation == "publish_gem"
 
           facts.merge(git_facts(version)).merge(changelog: flag(changelog?(version)))

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

@@ -29,7 +29,7 @@ module Hecks
           result = capture(script, *, env: env)
           return printed(result) if result.ok?
 
-          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+          raise ConsoleCapture::Failure, printed(result, ended(result))
         end
 
         # Runs the tool with the arguments and answers only what it printed to stdout, for a tool
@@ -45,7 +45,7 @@ module Hecks
           result = capture(script, *, env: env)
           return result.out.chomp if result.ok?
 
-          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+          raise ConsoleCapture::Failure, printed(result, ended(result))
         end
 
         # Runs the tool with the arguments and hands back how it ended.
@@ -73,6 +73,9 @@ module Hecks
           def success? = exitstatus.zero?
         end
 
+        # How a run that failed ended, for a failure that printed nothing.
+        def ended(result) = "ended with status #{result.exit_code}"
+
         def printed(result, otherwise = "")
           text = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
           text.empty? ? otherwise : text

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `Search` query asks of the working tree: the lines of its text files that
+      # match a regular expression, so a reader never has to leave the launcher for `grep`.
+      #
+      # Directories that hold no source of their own (version control, build output, vendored
+      # packages, scratch space, sibling worktrees) are left out, and so is any file with a null
+      # byte in its first block, which is how a binary announces itself.
+      module Search
+        # Directory names that are never walked.
+        SKIPPED = %w[.git .jj target node_modules tmp vendor worktrees].freeze
+
+        # The rows kept when `top` is not named.
+        DEFAULT_TOP = 200
+
+        # Searched when no path is named.
+        DEFAULT_PATHS = "."
+
+        # How much of a file is read to tell text from binary.
+        SNIFF_BYTES = 8192
+
+        module_function
+
+        # @param args [Hash] the query's arguments: `pattern`, `paths`, `top`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] one `path:line: text` row per match, in path order
+        # @raise [ConsoleCapture::Failure] when the pattern is not a regular expression
+        def report(args, tree)
+          matcher = compile(args.fetch(:pattern))
+          limit = args[:top] || DEFAULT_TOP
+          rows = []
+          files(tree, args[:paths] || DEFAULT_PATHS).each do |file|
+            matches(tree, file, matcher, limit, rows)
+            break if rows.length >= limit
+          end
+          rows.join("\n")
+        end
+
+        # @return [Regexp] the pattern, compiled
+        # @raise [ConsoleCapture::Failure] when it does not compile
+        def compile(pattern)
+          Regexp.new(pattern)
+        rescue RegexpError => e
+          raise ConsoleCapture::Failure, "not a regular expression: #{e.message}"
+        end
+
+        # @param limit [Integer] the most rows `rows` may hold
+        # @param rows [Array<String>] the rows so far; the matches of `file` are appended
+        def matches(tree, file, matcher, limit, rows)
+          File.foreach(tree.path(file), chomp: true).with_index(1) do |line, number|
+            break if rows.length >= limit
+            next unless line.valid_encoding? && matcher.match?(line)
+
+            rows << "#{file}:#{number}: #{line.strip}"
+          end
+        end
+
+        # @return [Array<String>] the text files under the named paths, relative to the root, sorted
+        def files(tree, paths)
+          named = paths.split(",").flat_map { |path| listing(tree, path) }
+          named.uniq.sort.select { |file| text?(tree, file) }
+        end
+
+        # @return [Array<String>] the files at one path: itself when a file, else all below it
+        def listing(tree, path)
+          return [path.delete_prefix("./")] if File.file?(tree.path(path))
+
+          below = Dir.glob("#{path.chomp("/")}/**/*", File::FNM_DOTMATCH, base: tree.root)
+          below.select { |entry| File.file?(tree.path(entry)) && walkable?(entry) }
+               .map { |entry| entry.delete_prefix("./") }
+        end
+
+        # @return [Boolean] whether no directory on the way to `entry` is one that is skipped
+        def walkable?(entry)
+          !entry.split("/")[0...-1].intersect?(SKIPPED)
+        end
+
+        # @return [Boolean] whether the file's first block holds no null byte
+        def text?(tree, file)
+          !File.binread(tree.path(file), SNIFF_BYTES).to_s.include?("\0")
+        end
+      end
+    end
+  end
+end

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

@@ -8,10 +8,13 @@ require_relative "regeneration"
 require_relative "gate"
 require_relative "style"
 require_relative "inspection"
+require_relative "search"
+require_relative "reading"
 require_relative "codemods"
 require_relative "test_suite"
 require_relative "corpus_tasks"
 require_relative "composing"
+require_relative "previewing"
 require_relative "publishing"
 require_relative "promotion"
 require_relative "../git"
@@ -75,6 +78,33 @@ module Hecks
         done.is_a?(Hash) ? done : { report: { value: done } }
       end
 
+      # @param args [Hash] the query's arguments: `pattern`, `paths`, `top`
+      # @return [Hash] `text:` the matching lines, one `path:line: text` row each
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the pattern is not a regular expression
+      def search(**args)
+        tree.require_checkout!
+        { text: Codebase::Search.report(args.transform_values { |value| plain(value) }, tree) }
+      end
+
+      # @param args [Hash] the query's arguments: `path`, `from`, `to`, `top`
+      # @return [Hash] `text:` the numbered lines of the file, one `line: text` row each
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the path is not a readable text file of the checkout
+      def read_source(**args) = { text: reading(:read, args) }
+
+      # @param args [Hash] the query's argument: `path`
+      # @return [Hash] `text:` what the file declares, one `from-to: kind name` row each
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the path is not a readable text file of the checkout
+      def outline(**args) = { text: reading(:outline, args) }
+
+      # @param args [Hash] the query's arguments: `name`, `kind`, `paths`, `show`
+      # @return [Hash] `text:` where the named construct is declared, one `path:from-to` row each
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when nothing by that name is declared
+      def declaration(**args) = { text: reading(:declaration, args) }
+
       # @return [Hash] `text:` where every word of the language stands
       # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
       def word_status(**)
@@ -169,6 +199,11 @@ module Hecks
         Codebase::TestSuite.report(operation, plain_args, tree, shell: self.class.shell)
       end
 
+      def reading(operation, args)
+        tree.require_checkout!
+        Codebase::Reading.public_send(operation, args.transform_values { |value| plain(value) }, tree)
+      end
+
       def corpus(operation, args)
         tree.require_checkout!
         plain_args = args.transform_values { |value| plain(value) }
@@ -184,8 +219,8 @@ module Hecks
       # The task families, each carrying out the operations it lists.
       FAMILIES = [Codebase::Language, Codebase::KernelTables, Codebase::Conformance, Codebase::Regeneration,
                   Codebase::Gate, Codebase::Style, Codebase::Inspection, Codebase::Codemods, Codebase::TestSuite,
-                  Codebase::CorpusTasks, Codebase::Composing, Codebase::Publishing,
-                  Codebase::Promotion].freeze
+                  Codebase::CorpusTasks, Codebase::Composing, Codebase::Previewing,
+                  Codebase::Publishing, Codebase::Promotion].freeze
       private_constant :FAMILIES
 
       # The facts of a promotion or a watch, naming the operation so policies can tell them apart.

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

@@ -0,0 +1,59 @@
+module Hecks
+  module Adapters
+    module Codebase
+      # A Rack app that serves the files under one directory and nothing outside it.
+      #
+      # A request for `/about` is answered by `about`, `about.html` or `about/index.html`, in that
+      # order, the way a static host with clean URLs answers it; `/` is answered by `index.html`.
+      class StaticDirectory
+        # @param root [String] the directory to serve
+        # @raise [ConsoleCapture::Failure] when the `rack` gem is not installed
+        def initialize(root)
+          self.class.load_rack
+          @root = File.realpath(root)
+          @files = Rack::Files.new(@root)
+        end
+
+        # @param env [Hash] the Rack environment
+        # @return [Array] the Rack response
+        def call(env)
+          return not_allowed unless %w[GET HEAD].include?(env["REQUEST_METHOD"])
+
+          found = resolve(Rack::Utils.unescape_path(env["PATH_INFO"].to_s))
+          return not_found unless found
+
+          @files.call(env.merge("PATH_INFO" => "/#{found}"))
+        end
+
+        # Loads Rack when a preview is asked for, so a checkout without the gem still boots.
+        #
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] naming the gem and how to add it
+        def self.load_rack
+          require "rack"
+        rescue LoadError
+          raise ConsoleCapture::Failure, "preview needs the rack gem: add `gem \"rack\"` to the Gemfile and bundle"
+        end
+
+        private
+
+        # @param path [String] the request path
+        # @return [String, nil] the file under the root, relative to it, or nil
+        def resolve(path)
+          relative = path.delete_prefix("/")
+          candidates = [relative, "#{relative}.html", File.join(relative, "index.html").delete_prefix("/")]
+          candidates.find { |candidate| inside?(candidate) }
+        end
+
+        def inside?(candidate)
+          full = File.expand_path(candidate, @root)
+          File.file?(full) && File.realpath(full).start_with?("#{@root}/")
+        end
+
+        def not_found = [404, { "content-type" => "text/plain" }, ["not found\n"]]
+
+        def not_allowed = [405, { "content-type" => "text/plain", "allow" => "GET, HEAD" }, ["GET and HEAD only\n"]]
+      end
+    end
+  end
+end

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

@@ -85,7 +85,7 @@ module Hecks
         rescue Errno::ENOENT
           raise ConsoleCapture::Failure, "no such file #{path} (relative to #{Dir.pwd}, tree #{tree.root})"
         rescue JSON::ParserError => e
-          raise ConsoleCapture::Failure, "#{path} is not JSON: #{e.message.lines.first.strip}"
+          raise ConsoleCapture::Failure, "#{path} is not JSON: #{Text.first_line(e.message)}"
         end
 
         # @param operation [String] `check_comments` or `check_rust_comments`
@@ -152,7 +152,7 @@ module Hecks
 
         # @param args [Hash] the record's plain fields
         # @return [Array<String>] the paths, from a comma-separated list
-        def paths_of(args) = args[:paths].to_s.split(",").map(&:strip).reject(&:empty?)
+        def paths_of(args) = Text.comma_list(args[:paths])
 
         # Paths as the linter takes them: after `--`, so no path is read as a flag.
         #

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

@@ -17,6 +17,21 @@ module Hecks
           # @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.
           attr_accessor :runner
+
+          # The runner is asked for from inside a command's own reaction cascade, and the
+          # dispatcher keeps that cascade's depth on the thread. A run starts at depth zero, as a
+          # plain run does, so work that cascades four deep is not cut off by the cascade that
+          # launched it.
+          #
+          # @yield the work to run at depth zero
+          # @return [Object] what the block answers
+          def at_reaction_depth_zero
+            depth = Thread.current[:hecks_reaction_depth]
+            Thread.current[:hecks_reaction_depth] = 0
+            yield
+          ensure
+            Thread.current[:hecks_reaction_depth] = depth
+          end
         end
 
         # @param tree [Tree] the checkout whose spec is run
@@ -28,13 +43,16 @@ module Hecks
         #
         # @param file [String] the spec file, relative to the checkout or absolute
         # @param example [String] part of the example's description
+        # @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, such as
+        #   `--tag cloudfront`
         # @return [String] what the runner printed when every matching example passed
         # @raise [ConsoleCapture::Failure] when the file is not there, or an example failed
-        def run(file:, example:)
+        def run(file:, example:, env: {}, tags: nil)
           path = File.expand_path(file, @tree.root)
           raise ConsoleCapture::Failure, "no such spec file #{file}" unless File.file?(path)
 
-          report = run_example(path, example)
+          report = with_env(env) { run_example(path, example, tags.to_s.split) }
           raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
 
           report
@@ -43,23 +61,24 @@ module Hecks
         private
 
         # What the runner printed for the example, when it passed.
-        def run_example(path, example)
+        def run_example(path, example, tags = [])
           out = StringIO.new
-          status = Dir.chdir(@tree.root) { at_reaction_depth_zero { runner.call(["--example", example, path], out, out) } }
+          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
         end
 
-        # The runner is asked for from inside a command's own reaction cascade, and the dispatcher
-        # keeps that cascade's depth on the thread. An example starts at depth zero, as a plain run
-        # does, so a spec that cascades four deep is not cut off by the cascade that launched it.
-        def at_reaction_depth_zero
-          depth = Thread.current[:hecks_reaction_depth]
-          Thread.current[:hecks_reaction_depth] = 0
+        def at_reaction_depth_zero(&) = self.class.at_reaction_depth_zero(&)
+
+        # Sets the variables for the block and puts each back as it was.
+        def with_env(env)
+          before = env.keys.to_h { |name| [name, ENV.fetch(name, nil)] }
+          env.each { |name, value| ENV[name] = value }
           yield
         ensure
-          Thread.current[:hecks_reaction_depth] = depth
+          before.each { |name, value| value.nil? ? ENV.delete(name) : ENV[name] = value }
         end
 
         def runner

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

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require_relative "tree"
 require_relative "test_runner"
 require_relative "sqlite_fixture"
+require_relative "cargo_tests"
+require_relative "cache_clearing"
 
 module Hecks
   module Adapters
@@ -17,7 +20,7 @@ module Hecks
       # 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
+        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
 
         # The tag filter the postgres job lists its specs by when none is named.
@@ -48,9 +51,21 @@ module Hecks
         # @raise [ConsoleCapture::Failure] when a run fails or a script is refused
         def call(operation, held, tree, shell: nil)
           args = plain(held)
+          case operation
+          when "run_spec_example" then spec_example(args, tree)
+          when "run_cargo_tests" then CargoTests.run(args, tree, shell)
+          when "clear_caches" then CacheClearing.clear
+          else tooling(operation, args, tree, shell)
+          end
+        end
+
+        # The operations that run one of the repository's own tools.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @return [String] what the tool printed
+        def tooling(operation, args, tree, shell)
           case operation
           when "refresh_runtime_baseline" then refresh(args, tree)
-          when "run_spec_example" then TestRunner.new(tree).run(file: args[:file], example: args[:example])
           when "stress_concurrency" then stress(args, tree)
           when "regenerate_legacy_fixtures" then regenerate_fixtures(args, tree, shell)
           when "seed_semantics_corpus" then seed(args, tree)
@@ -58,6 +73,25 @@ module Hecks
           end
         end
 
+        # @param args [Hash] `file`, `example`, and the arguments that set the specs' variables
+        # @param tree [Tree] the checkout
+        # @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])
+        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.
+        #
+        # @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
+        end
+
         # @param args [Hash] `runs`, `parallel` and `seed_start`
         # @param tree [Tree] the checkout
         # @return [String] what the stress run printed
@@ -73,11 +107,15 @@ module Hecks
           SqliteFixture.new(tree, shell: shell).regenerate(confirm: args[:confirm] == true)
         end
 
+        # Seeds at reaction depth zero, as a plain run would: the replay's sagas cascade, and the
+        # launching command's own cascade would otherwise cut them short.
+        #
         # @param args [Hash] `fixture`, perhaps absent
         # @param tree [Tree] the checkout
         # @return [String] what the seeding printed
         def seed(args, tree)
-          answer { command("seed_semantics_corpus").call(root: tree.root, env: seed_env(args)) }
+          seeding = command("seed_semantics_corpus")
+          answer { TestRunner.at_reaction_depth_zero { seeding.call(root: tree.root, env: seed_env(args)) } }
         end
 
         # A pure read: a listing, or the recorded pattern cases.