hecks 6.0.0 → 7.0.0

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "hecks/corpus"
+require_relative "tree"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `GeneratedKey` query asks of the working tree: the hash of everything
+      # regenerating some domains' Rust reads, which a cache of the generated tree is keyed on.
+      #
+      # The hash is `Hecks::Corpus::GeneratedKey`'s; this answers it in this process and turns a
+      # refusal of a domain name into the failure a query raises.
+      module GeneratedKeys
+        module_function
+
+        # @param args [Hash] the query's plain arguments: `domains` (feature names), `files`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] the hash, with each file hashed above it when `files` is true
+        # @raise [ConsoleCapture::Failure] when a name is not a domain, listing the valid ones
+        def report(args, tree)
+          names = args[:domains]&.split(",")
+          Corpus::GeneratedKey.report(names, files: args[:files] == true, root: tree.root)
+        rescue Corpus::UnknownDomain => e
+          raise ConsoleCapture::Failure, e.message
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "tree"
+require_relative "spec_files"
+require_relative "changed_specs"
+require_relative "../git_rehearsal/spec_map"
+require_relative "../git_rehearsal/impacted"
+require_relative "../git_rehearsal/impacted/skips"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The specs a branch's changes touch, found by the push rehearsal's own map and run in one
+      # launcher boot.
+      #
+      # The changed files are those between the merge base with the base ref and the working tree
+      # (uncommitted and untracked files included). `GitRehearsal::SpecMap` names the specs, and
+      # `GitRehearsal::Impacted::Skips` leaves out those that need `cargo`, `gh` or the network, and
+      # the `:io` ones when no scratch Postgres answers, exactly as the rehearsal's stage does.
+      class ImpactedSpecs
+        # The most spec files a run takes, as the rehearsal's stage does.
+        DEFAULT_CAP = GitRehearsal::Impacted::DEFAULT_LIMIT
+
+        DIGITS = /\d+/
+        TOTALS = /\d+ examples?, \d+ failures?\z/
+
+        # @param tree [Tree] the checkout
+        # @param scratch [#call, nil] says whether a scratch Postgres answers; `pg_isready` when nil
+        # @param files [SpecFiles, nil] runs the mapped specs
+        def initialize(tree, scratch: nil, files: nil)
+          @tree = tree
+          @scratch = scratch || -> { scratch_answers? }
+          @files = files || SpecFiles.new(tree)
+        end
+
+        # @param base [String] the ref the branch is compared with
+        # @param cap [Integer] the most spec files to run
+        # @param dry [Boolean] list the mapped specs and run none
+        # @param run_options [Hash] `isolation`, `example`, `env` and `tags`, as `SpecFiles#run`
+        #   takes them
+        # @return [String] the changed files, the mapped, skipped and run specs and how each ended
+        # @raise [ConsoleCapture::Failure] when git refuses or a spec fails
+        def call(base:, cap: DEFAULT_CAP, dry: false, **run_options)
+          changed = changed_files(base)
+          skips = GitRehearsal::Impacted::Skips.new(@tree.root, scratch: @scratch)
+          mapping = GitRehearsal::SpecMap.new(@tree.root).map(changed, limit: cap, skip: skips)
+          head = describe(base, changed, mapping)
+          return "#{head}\nnothing impacted; nothing run" if mapping.specs.empty?
+          return "#{head}\ndry run: no spec run" if dry
+
+          [head, run(mapping.specs, skips, run_options)].join("\n\n")
+        end
+
+        private
+
+        def changed_files(base)
+          merge, status = Open3.capture2e("git", "-C", @tree.root, "merge-base", "HEAD", base)
+          ChangedSpecs.changed_files(@tree, status.success? ? merge.strip : base)
+        end
+
+        def describe(base, changed, mapping)
+          lines = ["changed since #{base}: #{changed.size} file(s)", *changed.map { |file| "  #{file}" },
+                   "impacted specs: #{mapping.specs.size}", *mapping.specs.map { |spec| "  #{spec}" }]
+          lines << mapping.cap_note unless mapping.cap_note.empty?
+          (lines + mapping.skipped.map { |spec, why| "skipped: #{spec} (#{why})" }).join("\n")
+        end
+
+        # The `:io` specs run as CI does (`CI=true`), the rest as they are; with both, the report
+        # ends with the counts of both runs together.
+        def run(specs, skips, options)
+          io, plain = specs.partition { |spec| skips.io?(spec) }
+          env = options.fetch(:env, {})
+          groups = [[plain, env], [io, env.merge("CI" => "true")]].reject { |group, _env| group.empty? }
+          reports = groups.map { |group, group_env| batch(group, options.merge(env: group_env)) }
+          answer(reports)
+        end
+
+        def answer(reports)
+          text = (reports.map(&:text) + [(combined(reports) if reports.size > 1)]).compact.join("\n\n")
+          raise ConsoleCapture::Failure, text if reports.any?(&:failed)
+
+          text
+        end
+
+        # What a batch said, and whether a file of it failed.
+        Batch = Struct.new(:text, :failed)
+
+        def batch(group, options)
+          Batch.new(@files.run(files: group, **options), false)
+        rescue ConsoleCapture::Failure => e
+          Batch.new(e.message, true)
+        end
+
+        def combined(reports)
+          counts = reports.map { |report| final_counts(report.text) }
+          "#{counts.sum(&:first)} examples, #{counts.sum(&:last)} failures"
+        end
+
+        def final_counts(text) = text[TOTALS].scan(DIGITS).map(&:to_i)
+
+        def scratch_answers?
+          Open3.capture2e("pg_isready").last.success?
+        rescue SystemCallError
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -49,14 +49,14 @@ module Hecks
 
         # What the tool says after a proposal or a rename, which still needs hand work.
         FOLLOW_UP = {
-          "propose"          => "Proposed. It reaches no projection until admitted. Before `hecks admit`:\n  " \
+          "propose"          => "Proposed. It reaches no projection until admitted. Before `hecks language_run.admit!`:\n  " \
                                 "1. teach the %<context>s builder the word (and its spec/dsl_spec example)",
           "rename"           => "Renamed. The old spelling keeps parsing — that is the point. Before this holds:\n  " \
                                 "1. alias the new word to the old in the %<context>s builder " \
                                 "(alias_method :%<new_name>s, :%<word>s)\n  " \
                                 "2. add the identical-IR example to spec/dsl_spec.rb",
           "propose_argument" => "Proposed. It reaches no projection until admitted. Before " \
-                                "`hecks admit_argument`:\n  " \
+                                "`hecks language_run.admit_argument!`:\n  " \
                                 "1. teach the %<context>s builder's %<word>s method the argument"
         }.freeze
 

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "hecks/command_names"
+require "hecks/workflow_pagination"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `ConformanceRun` asks of the text that drives the launcher and GitHub: the
+      # workflows, hooks, gate rows, specs and guides.
+      #
+      # Both checks read files in this process and write nothing. They look for the two ways such
+      # text goes quietly wrong: a command name the launcher does not accept, and a count of
+      # GitHub list items taken from the first page only.
+      module LauncherText
+        module_function
+
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] the clean verdict
+        # @raise [ConsoleCapture::Failure] with each invocation the launcher would refuse
+        def command_names(tree)
+          runtime = Hecks.describe(tree.path("lib/hecks/hecks"))
+          CommandNames.check(root: tree.root, runtime: runtime)
+        rescue CommandNames::Failure => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @param tree [Tree] the working tree
+        # @return [String] the clean verdict
+        # @raise [ConsoleCapture::Failure] with each list call that counts one page
+        def workflow_pagination(tree)
+          WorkflowPagination.check(root: tree.root)
+        rescue WorkflowPagination::Failure => e
+          raise ConsoleCapture::Failure, e.message
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The minitest files of a spec directory. RSpec does not run them, so each one runs in its own Ruby
+      # process, and its run summary is reported beside the RSpec output.
+      module MinitestRuns
+        # The summary line minitest prints, such as "3 runs, 5 assertions".
+        SUMMARY = /\d+ runs?, /
+
+        module_function
+
+        # @param tree [Tree] the folder whose specs are listed
+        # @return [Array<String>] their paths, relative to the folder, sorted
+        def files(tree)
+          Dir.glob("#{TestSuite::SPEC_DIRECTORY}/**/*_test.rb", base: tree.root).sort
+        end
+
+        # Runs each file in its own Ruby process, from the folder, outside this process's bundle so the
+        # folder's own gems are the ones it loads.
+        #
+        # @param tree [Tree] the folder the files run in
+        # @param files [Array<String>] the minitest files
+        # @return [Array<String>] one line per file: its path and its run summary
+        # @raise [ConsoleCapture::Failure] with the output of the first file that fails
+        def reports(tree, files)
+          files.map do |file|
+            out, status = unbundled { Open3.capture2e(RbConfig.ruby, file, chdir: tree.root) }
+            raise ConsoleCapture::Failure, "#{file} failed\n#{out.strip}" unless status.success?
+
+            "#{file}: #{summary(out)}"
+          end
+        end
+
+        # @param out [String] what a minitest file printed
+        # @return [String] its last run summary line, or nothing when it printed none
+        def summary(out)
+          matches = out.lines.grep(SUMMARY)
+          matches.last.to_s.strip
+        end
+
+        # Runs the block without the bundle this process was started under, when Bundler is loaded.
+        def unbundled(&)
+          defined?(Bundler) ? Bundler.with_unbundled_env(&) : yield
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 
 require_relative "tree"
 require_relative "ruby_child"
+require "hecks/tools/gate_memo/standalone"
 
 module Hecks
   module Adapters
@@ -10,13 +11,16 @@ module Hecks
       # domain's committed Rust output, and projecting the CI path gates into the workflows.
       #
       # It runs `Hecks::Tools::RegenerationRun` in this process: the run forks once for each
-      # domain, in a fixed order, because the domains share the files they stamp. With `check` it
-      # projects into a scratch copy of the crate and compares, and never writes the tree. Without
-      # `confirm` the run is that same check, so a regeneration that would rewrite tracked generated
-      # files reports drift and writes only when it is confirmed.
+      # domain, a few at a time (`workers`, one per core unless told), and prints their output in
+      # a fixed domain order. The domains share the bluebooks they attach, and each writes the same
+      # bytes to them whichever runs first. With `check` it projects into a scratch copy of the
+      # crate and compares, and never writes the tree. Without `confirm` the run is that same
+      # check, so a regeneration that would rewrite tracked generated files reports drift and
+      # writes only when it is confirmed.
       module Regeneration
         # Every operation this family carries out.
-        OPERATIONS = %w[regenerate_corpus project_ci_gates project_lanes project_tools_doc decide_ci_gate].freeze
+        OPERATIONS = %w[regenerate_corpus project_ci_gates project_ci_pipeline project_lanes project_tools_doc
+                        decide_ci_gate].freeze
 
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
@@ -40,13 +44,42 @@ module Hecks
           child = RubyChild.new(tree)
           case operation
           when "project_ci_gates" then project_ci_gates(child, check)
+          when "project_ci_pipeline" then project_ci_pipeline(child, check)
           when "project_lanes" then project_lanes(child, check, set?(held, :live), set?(held, :confirm))
           when "project_tools_doc" then project_tools_doc(child, check)
           when "decide_ci_gate" then decide_ci_gate(child, held)
-          else regenerate(child, check)
+          else regenerate_remembered(child, tree, held, check)
           end
         end
 
+        # A check of the whole corpus that is not confirmed is skipped when the gate or an earlier
+        # check passed on the same files. A run that writes, or checks only some domains, always
+        # runs.
+        #
+        # @return [String] the verdict, or that the check was skipped as unchanged
+        def regenerate_remembered(child, tree, held, check)
+          args = [*domains(held), *workers(held)]
+          whole = check && args.empty? && !set?(held, :confirm)
+          return regenerate(child, check, args) unless whole
+
+          Tools::GateMemo::Standalone.guard(tree.root, "codegen_drift") { regenerate(child, check, args) }
+        end
+
+        # @param held [Hash] the `RegenerationRun` record's fields: `domains`
+        # @return [Array<String>] the tool's argument naming the domains to run, empty for every one
+        def domains(held)
+          named = held[:domains].is_a?(Hash) ? held[:domains][:value] : held[:domains]
+          named.to_s.empty? ? [] : ["domains=#{named}"]
+        end
+
+        # @param held [Hash] the `RegenerationRun` record's fields: `workers`
+        # @return [Array<String>] the tool's argument saying how many domains run at once, empty to
+        #   leave it to the tool's default
+        def workers(held)
+          count = held[:workers].is_a?(Hash) ? held[:workers][:value] : held[:workers]
+          count.to_s.empty? ? [] : ["workers=#{count}"]
+        end
+
         # @param held [Hash] the record's fields: `check`, `confirm`
         # @return [Boolean] whether the run only compares: asked for, or not confirmed
         def check_only?(held)
@@ -62,10 +95,12 @@ module Hecks
 
         # @param child [RubyChild] the checkout's tool runner
         # @param check [Boolean] whether to only compare
+        # @param domains [Array<String>] `domains=a,b` when only those are to run and `workers=n`
+        #   when told how many at once, else empty
         # @return [String] how many domains were checked or regenerated
         # @raise [ConsoleCapture::Failure] with the difference, or with what the script printed
-        def regenerate(child, check)
-          result = child.capture("regen_codegen_domains", *("--check" if check))
+        def regenerate(child, check, domains = [])
+          result = child.capture("regen_codegen_domains", *("--check" if check), *domains)
           raise ConsoleCapture::Failure, refusal(result) unless result.ok?
 
           summary(result.out, check)
@@ -79,6 +114,14 @@ module Hecks
           child.answer("project_ci_gates", *("--check" if check))
         end
 
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare
+        # @return [String] what the tool printed
+        # @raise [ConsoleCapture::Failure] with the stale workflows, when a check finds drift
+        def project_ci_pipeline(child, check)
+          child.answer("project_ci_pipeline", *("--check" if check))
+        end
+
         # Projects the `Lane` rows, or with `live` compares GitHub's rulesets with them. Only a live
         # run that is confirmed changes GitHub, so without `confirm` a live run is a comparison.
         #

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What a spec run's arguments become: the variables the specs read, and the flags a stress run takes.
+      # A person names them in a request, so they never set them in a shell.
+      module RunOptions
+        module_function
+
+        # The variables the specs read, set for one example only.
+        #
+        # @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`
+        # @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] } : {}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../../../tools/move_disables"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `ScriptRun` asks of the working tree: one named one-off script, planned, or
+      # applied once confirmed. A script's body is a tool under `lib/hecks/tools`; `SCRIPTS` names
+      # the ones this family may run, so a record cannot reach a tool it does not list.
+      module Scripting
+        # Every operation this family carries out.
+        OPERATIONS = %w[plan_script apply_script].freeze
+
+        # Each script a record may name, with the tool that carries it out.
+        SCRIPTS = { "move_disables" => Hecks::Tools::MoveDisables }.freeze
+
+        module_function
+
+        # Carries out one operation on the named script.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `ScriptRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused: the tool runs in this process
+        # @return [String] the tool's plan, or the plan and what it wrote
+        # @raise [ConsoleCapture::Failure] when the record names no script this family runs
+        def call(operation, held, tree, shell: nil)
+          args = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          name = args[:script].to_s
+          tool = SCRIPTS.fetch(name) do
+            raise ConsoleCapture::Failure, "no script named #{name.inspect}; the scripts are #{SCRIPTS.keys.join(", ")}"
+          end
+          tool.transform(root: tree.root, apply: operation == "apply_script")
+        end
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Hecks
       # 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
+        SKIPPED = %w[.git target node_modules tmp vendor worktrees].freeze
 
         # The rows kept when `top` is not named.
         DEFAULT_TOP = 200

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

@@ -10,17 +10,44 @@ require_relative "style"
 require_relative "inspection"
 require_relative "search"
 require_relative "reading"
+require_relative "corpus_queries"
+require_relative "generated_keys"
 require_relative "codemods"
 require_relative "test_suite"
+require_relative "test_scope"
 require_relative "corpus_tasks"
 require_relative "composing"
 require_relative "previewing"
 require_relative "publishing"
 require_relative "promotion"
+require_relative "scripting"
 require_relative "../git"
 
 module Hecks
   module Adapters
+    # The lookup and working tree a perform runs against, kept out of the class body.
+    module Performing
+      # @param operation [String] the operation the request names
+      # @return [Module] the family that carries it out
+      # @raise [ConsoleCapture::Failure] when no family carries the operation out
+      def family_for(operation)
+        SourceTree::FAMILIES.find { |candidate| candidate::OPERATIONS.include?(operation) } ||
+          raise(ConsoleCapture::Failure, "no task carries out #{operation.inspect}")
+      end
+
+      # @param operation [String] the operation the request names
+      # @param held [Hash] the record, whose folder argument a folder operation reads
+      # @return [Object] the tree the operation runs against
+      def working_tree(operation, held)
+        Codebase::TestSuite::FOLDER_OPERATIONS.include?(operation) ? folder_tree(held) : checkout_tree
+      end
+
+      # @return [Object] the shell the family runs commands through
+      def shell
+        self.class.shell || Shell.new
+      end
+    end
+
     # The `SourceTree` port's adapter: everything Codebase does to the working tree of this
     # repository.
     #
@@ -31,6 +58,9 @@ module Hecks
     # `perform` finds the task family that carries an operation out; a family lives beside this
     # file and does the work with the existing generators, linters and tools.
     class SourceTree
+      include CorpusQueries
+      include Performing
+
       class << self
         # @return [#capture, nil] starts each child process; a `Shell` when nil. A spec replaces it
         #   so no gate has to run to test what is asked of it.
@@ -42,7 +72,10 @@ module Hecks
       # @param aggregate [Object, nil] unused
       # @param settings [Hash] unused
       # @param root [String, nil] unused
-      def initialize(aggregate: nil, settings: {}, root: nil); end
+      # @param registry [Runtime::Registry, nil] whose Hecks world declares the `test_scope` limit
+      def initialize(aggregate: nil, settings: {}, root: nil, registry: nil)
+        @registry = registry
+      end
 
       # Reports whether the working tree is a hecks checkout. For a release it also reports the
       # facts the Git adapter surveys, since a release's rules are judged with the checkout rule.
@@ -51,8 +84,10 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `checkout:` whether hecks.gemspec stands beside lib/, and for
       #   a release the facts to judge
       def examine(**held)
-        answer = { checkout: { value: tree.checkout? } }
         operation = plain(held[:operation])
+        return { checkout: { value: folder_specs?(held) } } if Codebase::TestSuite::FOLDER_OPERATIONS.include?(operation)
+
+        answer = { checkout: { value: tree.checkout? } }
         return answer.merge(promotion_facts(held)) if Codebase::Promotion::OPERATIONS.include?(operation)
         return answer unless Codebase::Publishing::OPERATIONS.include?(operation)
 
@@ -68,13 +103,13 @@ module Hecks
       # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
       # @raise [ConsoleCapture::Failure] when no family carries the operation out, or it refuses
       def perform(**held)
-        tree.require_checkout!
         operation = plain(held[:operation])
-        family = FAMILIES.find { |candidate| candidate::OPERATIONS.include?(operation) }
-        raise ConsoleCapture::Failure, "no task carries out #{operation.inspect}" unless family
+        return handed_off(operation) if HANDED_OFF.include?(operation)
 
-        args = held.except(:operation)
-        done = family.call(operation, args, tree, shell: self.class.shell || Shell.new)
+        family = family_for(operation)
+        folder = working_tree(operation, held)
+        allowed = Codebase::TestScope.new(@registry).admit(operation, held.except(:operation), folder)
+        done = family.call(operation, allowed, folder, shell: shell)
         done.is_a?(Hash) ? done : { report: { value: done } }
       end
 
@@ -150,46 +185,26 @@ module Hecks
         { text: test_suite("record_pattern_cases", {}) }
       end
 
-      # @return [Hash] `text:` the feature and directory of every domain with a Rust feature
-      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
-      def rust_domains(**)
-        { text: corpus("rust_domains", {}) }
-      end
-
-      # @return [Hash] `text:` the directories regeneration walks, in the order it walks them
-      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
-      def regen_order(**)
-        { text: corpus("regen_order", {}) }
-      end
-
-      # @return [Hash] `text:` whether each generated Rust module is covered
-      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
-      # @raise [ConsoleCapture::Failure] when a module is not covered
-      def corpus_rust_coverage(**)
-        { text: corpus("corpus_rust_coverage", {}) }
-      end
-
-      # @param args [Hash] the query's arguments: `names`
-      # @return [Hash] `text:` each IR construct's diff from its meta-domain
+      # @param args [Hash] the query's arguments: `domains` (feature names), `files`
+      # @return [Hash] `text:` the hash of what regenerating those domains reads, with `files` each
+      #   file hashed above it
       # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
-      def ir_constructs(**args)
-        { text: corpus("ir_constructs", args) }
+      # @raise [ConsoleCapture::Failure] when a name is not a domain, listing the valid ones
+      def generated_key(**args)
+        tree.require_checkout!
+        { text: Codebase::GeneratedKeys.report(args.transform_values { |value| plain(value) }, tree) }
       end
 
-      # @param args [Hash] the query's arguments: `domains`, `meta`
-      # @return [Hash] `text:` the rules declared more than once
-      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
-      def ir_duplicates(**args)
-        { text: corpus("ir_duplicates", args) }
-      end
+      # Operations the Terminal adapter carries out itself: the run records that the server was
+      # started and answers when the process hands back, so nothing here runs them.
+      HANDED_OFF = %w[serve_mcp].freeze
+      private_constant :HANDED_OFF
 
-      # @param args [Hash] the query's arguments: `name`, `field`
-      # @return [Hash] `text:` which propagation touchpoints already show the field
-      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
-      # @raise [ConsoleCapture::Failure] when the construct is not one
-      def ir_impact(**args)
-        { text: corpus("ir_impact", args) }
-      end
+      # 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::Previewing,
+                  Codebase::Publishing, Codebase::Promotion, Codebase::Scripting].freeze
 
       private
 
@@ -216,21 +231,34 @@ module Hecks
         Codebase::Style.report(operation, plain_args, tree, shell: self.class.shell)
       end
 
-      # 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::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.
       def promotion_facts(held)
         facts = tree.checkout? ? Codebase::Promotion.facts(held, tree) : Codebase::Promotion.no_facts
-        { operation: held[:operation], alert_key: held[:alert_key] }.compact.merge(facts)
+        { operation: held[:operation] }.compact.merge(facts)
+      end
+
+      # @return [Hash{Symbol => Hash}] `report:` the note that the terminal carries the operation
+      def handed_off(operation)
+        note = { value: "#{operation} handed to the terminal" }
+        { report: note, output: note }
       end
 
       def tree = Codebase::Tree.new
 
+      # The checkout this repository's own tooling works on, which must be a hecks checkout.
+      def checkout_tree
+        tree.require_checkout!
+        tree
+      end
+
+      # The folder a spec run works in: the one the request names, this checkout when none is.
+      def folder_tree(held) = Codebase::Tree.new(root: plain(held[:root]))
+
+      # Whether the folder a spec run names holds a spec directory, so any project's suite can run.
+      def folder_specs?(held)
+        File.directory?(File.join(folder_tree(held).root, Codebase::TestSuite::SPEC_DIRECTORY))
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end