hecks 2.8.0 → 3.0.0

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "hecks/release/runner"
+require_relative "tree"
+require_relative "gem_registry"
+require_relative "secret_vault"
+require_relative "release_facts"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `PublishingRun` asks of the working tree once the release is cleared:
+      # cutting the release, or pushing the gem alone.
+      #
+      # A release is `Hecks::Release::Runner`: it tags the release commit, publishes the gem and
+      # gets the client package published, skipping what a registry already lists. Its rules were
+      # judged before it starts (the givens of `Clear`), so it is handed the facts they cleared and
+      # checks only that its tools are installed. Unconfirmed it is the dry run: every check and
+      # build, and nothing tagged, pushed or published. The answer says which steps were really
+      # carried out, so the journal can advance the root `Release`: tagged, published, verified.
+      module Publishing
+        # Every operation this family carries out.
+        OPERATIONS = %w[publish publish_gem].freeze
+
+        class << self
+          # @return [#capture, #run!, nil] starts every process a release runs; the real ones
+          #   (`Hecks::Release::Runner::Commands`) when nil. A spec replaces it, so nothing is
+          #   tagged, pushed, published or fetched.
+          attr_accessor :commands
+
+          # @return [Hash] extra arguments for the release, such as `pause:` and `now:`, so a spec
+          #   can wait for the registry without sleeping
+          attr_accessor :release_options
+        end
+
+        module_function
+
+        # The facts of a tree that is not a checkout: placeholders that satisfy the value objects,
+        # so the checkout rule is the one that refuses.
+        #
+        # @param operation [String] `publish` or `publish_gem`
+        # @return [Hash] every fact a release is judged by, none of them true
+        def no_facts(operation)
+          none = { value: "none" }
+          { operation: { value: operation }, version: { value: "0.0.0" }, client_version: { value: "0.0.0" },
+            ir_version: { value: "0.0.0" }, ships_from: { path: "none" }, branch: none, head: none,
+            tag_state: none, on_origin: { value: false }, clean: { value: false }, changelog: { value: false } }
+        end
+
+        # Carries out an accepted request.
+        #
+        # @param operation [String] `publish` or `publish_gem`
+        # @param held [Hash] the `PublishingRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused; the release starts its own processes
+        # @return [Hash] `report`, `tagged`, `published` and `verified`, and `version` for the
+        #   `Release` record
+        # @raise [ConsoleCapture::Failure] when the release refuses or a step fails, with its words
+        def call(operation, held, tree, shell: nil)
+          _ = shell
+          args = held.transform_values { |value| value.is_a?(Hash) && value.key?(:value) ? value[:value] : value }
+          commands = Publishing.commands || Release::Runner::Commands.new
+          if operation == "publish_gem"
+            publish_gem(args, tree, commands)
+          else
+            publish(args, tree, commands)
+          end
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param commands [#capture, #run!] starts each process
+        # @return [Hash] what the release did
+        # @raise [ConsoleCapture::Failure] when the release stops before any real step; one that
+        #   stops after a real step answers, with `succeeded` false, so the steps are recorded
+        def publish(args, tree, commands)
+          out = StringIO.new
+          err = StringIO.new
+          runner = release(args, tree, commands, out, err)
+          status = runner.call
+          text = [out.string, err.string].map(&:strip).reject(&:empty?).join("\n")
+          raise ConsoleCapture::Failure, text if !status.zero? && runner.steps.empty?
+
+          outcome(text, args, tagged: runner.steps.include?(:tagged), published: runner.steps.include?(:gem),
+                              verified: runner.verified, succeeded: status.zero?)
+        end
+
+        # @return [Hecks::Release::Runner] the release, over the facts the run was cleared by
+        def release(args, tree, commands, out, err)
+          flag = ->(name) { args[name] == true }
+          options = Release::Runner::Options.new(dry_run: args[:confirm] != true, gem_only: flag.call(:gem_only),
+                                                 npm_only: flag.call(:npm_only), npm_local: flag.call(:npm_local),
+                                                 no_wait: flag.call(:no_wait), yes: true)
+          facts = Release::Runner::Preflight::Facts.new(version: args[:version], sha: args[:head])
+          Release::Runner.new(root: tree.root, options: options, commands: commands, input: StringIO.new, out: out,
+                              err: err, facts: facts, **(Publishing.release_options || {}))
+        rescue ArgumentError => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # Pushes the gem alone, or builds it and deletes it again when unconfirmed.
+        #
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param commands [#capture, #run!] starts each process
+        # @return [Hash] what was done
+        # @raise [ConsoleCapture::Failure] when the build or the push fails, or the vault is missing
+        def publish_gem(args, tree, commands)
+          registry = GemRegistry.new(root: tree.root, commands: commands)
+          version = args[:version]
+          return dry_gem(registry, version, args) unless args[:confirm] == true
+          raise ConsoleCapture::Failure, "1Password CLI (op) not found; install it: brew install 1password-cli" unless
+            SecretVault.new(commands: commands).installed?
+
+          registry.push!(version)
+          verified = registry.published?(version)
+          outcome("Released hecks #{version}.", args, tagged: false, published: true, verified: verified)
+        rescue Release::Runner::CommandFailed, Release::Runner::Refusal => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @return [Hash] the answer of a gem push that only built the gem
+        def dry_gem(registry, version, args)
+          registry.build_only!(version)
+          outcome("dry run, built hecks-#{version}.gem and deleted it; nothing was pushed (add --confirm)",
+                  args, tagged: false, published: false, verified: false)
+        rescue Release::Runner::CommandFailed => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @return [Hash] the answer the journal records: a report, what was done, and the release
+        def outcome(text, args, tagged:, published:, verified:, succeeded: true)
+          { report: { value: text }, tagged: { value: tagged }, published: { value: published },
+            verified: { value: verified }, succeeded: { value: succeeded }, version: { value: args[:version] },
+            ir_version: { value: args[:ir_version] }, ships_from: args[:ships_from] }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "ruby_child"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `RegenerationRun` asks of the working tree: regenerating every corpus
+      # domain's committed Rust output.
+      #
+      # 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.
+      module Regeneration
+        # Every operation this family carries out.
+        OPERATIONS = %w[regenerate_corpus].freeze
+
+        # How many lines of a script's output a refusal keeps.
+        KEPT_LINES = 60
+
+        module_function
+
+        # Carries out the regeneration.
+        #
+        # @param _operation [String] `regenerate_corpus`
+        # @param held [Hash] the `RegenerationRun` record's fields: `check`, `confirm`
+        # @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] how many domains were checked or regenerated
+        # @raise [ConsoleCapture::Failure] with the difference, when a check finds drift, or with
+        #   what the script printed when it ends badly
+        def call(_operation, held, tree, shell: nil)
+          flag = ->(name) { (held[name].is_a?(Hash) ? held[name][:value] : held[name]) == true }
+          check = flag.call(:check) || !flag.call(:confirm)
+          child = RubyChild.new(tree)
+          result = child.capture("regen_codegen_domains", *("--check" if check))
+          raise ConsoleCapture::Failure, refusal(result) unless result.ok?
+
+          summary(result.out, check)
+        end
+
+        # @param output [String] what the script printed
+        # @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]
+          return "regenerated #{count} corpus domains into the checkout" unless check
+
+          "checked #{count} corpus domains against a scratch crate: no drift " \
+            "(add --confirm to regenerate into the checkout)"
+        end
+
+        # @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?)
+          shown = lines.last(KEPT_LINES)
+          note = lines.size > shown.size ? ["(the last #{shown.size} of #{lines.size} lines)"] : []
+          [*note, *shown].join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks/release/runner"
+require_relative "tree"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The facts a release is judged by, read from git and the checkout's files and judged by
+      # nothing here: the rules are the givens of the `Clear` command of `PublishingRun`.
+      #
+      # It reads the branch, whether `HEAD` is `origin/main` (after a fetch), whether the tree is
+      # clean, the gem's version and the client package's, whether the changelog has a heading for
+      # the version, and where a tag for the version already points. Nothing is changed but the
+      # remote-tracking refs a fetch updates.
+      class ReleaseFacts
+        # The line of `lib/hecks/version.rb` that declares the version.
+        VERSION_LINE = /^\s*VERSION\s*=\s*"(?<version>[^"]+)"/
+
+        # Where the client package declares its version, relative to the checkout.
+        CLIENT_PACKAGE = "packages/hecks-client/package.json"
+
+        # @param tree [Tree] the checkout
+        # @param commands [#capture, #run!] starts each process, as `Release::Runner::Commands` does
+        def initialize(tree, commands:)
+          @tree = tree
+          @git = Release::Runner::Git.new(root: tree.root, commands: commands)
+        end
+
+        # Reads the facts a run of the operation needs.
+        #
+        # @param operation [String] `publish` (every fact) or `publish_gem` (the versions only)
+        # @return [Hash] each fact as the run holds it: every one a value object
+        #   as a hash, and `ships_from` the checkout's path
+        # @raise [ConsoleCapture::Failure] when git or a file cannot be read
+        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 } }
+          return facts if operation == "publish_gem"
+
+          facts.merge(git_facts(version)).merge(changelog: flag(changelog?(version)))
+        rescue Release::Runner::Refusal, Errno::ENOENT, JSON::ParserError, KeyError => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        private
+
+        def git_facts(version)
+          fetch = @git.capture("fetch", "origin")
+          raise ConsoleCapture::Failure, "git fetch origin failed (#{fetch.stderr.strip})" unless fetch.success?
+
+          head = read("rev-parse", "HEAD")
+          { branch: word(read("rev-parse", "--abbrev-ref", "HEAD")), head: word(head),
+            on_origin: flag(head == read("rev-parse", "origin/main")),
+            clean: flag(read("status", "--porcelain").empty?), tag_state: word(tag_state("v#{version}", head)) }
+        end
+
+        def tag_state(tag, head)
+          tagger = Release::Runner::Tagger.new(git: @git, console: nil, dry_run: true)
+          commits = [tagger.local_commit(tag), tagger.remote_commit(tag)].compact
+          return "none" if commits.empty?
+
+          commits.all?(head) ? "at_release_commit" : "elsewhere"
+        end
+
+        def read(*) = @git.read(*).strip
+
+        def declared_version
+          match = File.read(@tree.path("lib/hecks/version.rb")).match(VERSION_LINE)
+          raise Release::Runner::Refusal, "lib/hecks/version.rb declares no VERSION; restore it" unless match
+
+          match[:version]
+        end
+
+        def client_version = JSON.parse(File.read(@tree.path(CLIENT_PACKAGE))).fetch("version")
+
+        def changelog?(version)
+          File.read(@tree.path("CHANGELOG.md")).match?(/^## \[#{Regexp.escape(version)}\]/)
+        end
+
+        def word(text) = { value: text }
+
+        def flag(truth) = { value: truth }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "../shell"
+require_relative "../console_capture"
+require "hecks/tools"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # Runs one of this repository's own tools, by its name in `Hecks::Tools::REGISTRY`.
+      #
+      # The tool runs in this process from the checkout's root, its output and exit status
+      # captured: the gem carries every tool, so nothing is started as a child.
+      class RubyChild
+        # @param tree [Tree] the checkout the tool belongs to
+        def initialize(tree)
+          @tree = tree
+        end
+
+        # Runs the tool with the arguments and answers what it printed.
+        #
+        # @param script [String] the tool's name in `Hecks::Tools::REGISTRY`
+        # @param args [Array<String>] its arguments
+        # @param env [Hash{String => String}] unused; a tool reads this process's environment
+        # @return [String] what it wrote to stdout, and to stderr when there was any
+        # @raise [ConsoleCapture::Failure] when it ends with a non-zero status; the message is
+        #   everything it printed
+        def answer(script, *, env: {})
+          result = capture(script, *, env: env)
+          return printed(result) if result.ok?
+
+          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+        end
+
+        # Runs the tool with the arguments and answers only what it printed to stdout, for a tool
+        # whose stdout is its data and whose stderr is progress.
+        #
+        # @param script [String] the tool's name in `Hecks::Tools::REGISTRY`
+        # @param args [Array<String>] its arguments
+        # @param env [Hash{String => String}] unused; a tool reads this process's environment
+        # @return [String] its stdout, without the trailing newline
+        # @raise [ConsoleCapture::Failure] when it ends with a non-zero status; the message is
+        #   everything it printed
+        def read(script, *, env: {})
+          result = capture(script, *, env: env)
+          return result.out.chomp if result.ok?
+
+          raise ConsoleCapture::Failure, printed(result, "ended with status #{result.status.exitstatus}")
+        end
+
+        # Runs the tool with the arguments and hands back how it ended.
+        #
+        # @param script [String] the tool's name in `Hecks::Tools::REGISTRY`
+        # @param args [Array<String>] its arguments
+        # @param env [Hash{String => String}] unused; a tool reads this process's environment
+        # @return [Shell::Result] its output (stderr included) and status
+        # @raise [KeyError] when no tool has that name
+        def capture(script, *args, env: {})
+          in_process(script, args)
+        end
+
+        private
+
+        def in_process(script, args)
+          code = nil
+          outcome = ConsoleCapture.capture { code = Tools.run(script, args, root: @tree.root) }
+          Shell::Result.new(outcome.output, "", Status.new(code))
+        end
+
+        # How a tool run in this process ended, answering as a `Process::Status` does.
+        Status = Struct.new(:exitstatus) do
+          # @return [Boolean] whether it ended with status 0
+          def success? = exitstatus.zero?
+        end
+
+        def printed(result, otherwise = "")
+          text = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
+          text.empty? ? otherwise : text
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `SecretVault` adapter: runs a program with the secrets a 1Password `op run` env file
+      # names, so a key or token never sits in a file, a variable of ours or a command line.
+      #
+      # It starts `op` through the object it is given, which answers `capture` and `run!` as
+      # `Hecks::Release::Runner::Commands` does; a spec hands it a recorder.
+      class SecretVault
+        # @param commands [#capture, #run!] starts each process
+        def initialize(commands:)
+          @commands = commands
+        end
+
+        # @return [Boolean] whether the 1Password CLI is installed
+        def installed?
+          @commands.capture("op", "--version").success?
+        end
+
+        # Runs a program with the env file's secrets in its environment, its output going to the
+        # terminal so a prompt (Touch ID, an approval link) reaches the person.
+        #
+        # @param env_file [String] the env file `op run` reads, absolute or relative to `chdir`
+        # @param argv [Array<String>] the program and its arguments
+        # @param chdir [String, nil] the directory to run in
+        # @return [true] when the program exits zero
+        # @raise [Hecks::Release::Runner::CommandFailed] when it does not
+        def run!(env_file, *argv, chdir: nil)
+          @commands.run!("op", "run", "--env-file=#{env_file}", "--", *argv, chdir: chdir)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/codebase/source_tree"
+
+Hecks.adapter "SourceTree" do
+  port "SourceTree"
+end

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "language"
+require_relative "kernel_tables"
+require_relative "conformance"
+require_relative "regeneration"
+require_relative "style"
+require_relative "codemods"
+require_relative "test_suite"
+require_relative "corpus_tasks"
+require_relative "publishing"
+require_relative "../git"
+
+module Hecks
+  module Adapters
+    # The `SourceTree` port's adapter: everything Codebase does to the working tree of this
+    # repository.
+    #
+    # It answers the one fact every Codebase request needs (`examine`: is the tree a hecks
+    # checkout?), carries out an accepted request (`perform`), and answers Codebase's queries. Each
+    # of them refuses "needs a hecks checkout" outside a checkout, so an installed gem never touches
+    # an absent `rust/` or rewrites its own `lib/`, even when the journaled guard is bypassed.
+    # `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
+      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.
+        attr_accessor :shell
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); 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.
+      #
+      # @param held [Hash] the record: `operation`
+      # @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 answer unless Codebase::Publishing::OPERATIONS.include?(operation)
+
+        facts = tree.checkout? ? Git.new.survey(**held) : Codebase::Publishing.no_facts(operation)
+        answer.merge(facts)
+      end
+
+      # Carries out the operation an accepted request names.
+      #
+      # @param held [Hash] the record: `operation` and every argument the request set
+      # @return [Hash{Symbol => Hash}] `report:` what was found, or done; a task that does more
+      #   than report (a release) answers its own fields, `report:` among them
+      # @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
+
+        args = held.except(:operation)
+        done = family.call(operation, args, tree, shell: self.class.shell || Shell.new)
+        done.is_a?(Hash) ? done : { report: { value: done } }
+      end
+
+      # @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(**)
+        tree.require_checkout!
+        { text: Codebase::Language.word_status }
+      end
+
+      # @param args [Hash] the query's arguments: `paths`, `only`, `json`, `top`
+      # @return [Hash] `text:` the Ruby comment violations, as the linter reports them
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the linter refuses its arguments
+      def report_comments(**args)
+        { text: report("report_comments", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `paths`, `only`, `json`, `top`
+      # @return [Hash] `text:` the Rust comment violations, as the linter reports them
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the linter refuses its arguments
+      def report_rust_comments(**args)
+        { text: report("report_rust_comments", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `group`, `groups`, `runtime_log`
+      # @return [Hash] `text:` the spec files one group of a runtime-balanced split runs
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the script refuses its arguments
+      def shard_specs(**args)
+        { text: test_suite("shard_specs", args) }
+      end
+
+      # @param args [Hash] the query's arguments: `exclude`, `tags`, `check`
+      # @return [Hash] `text:` the spec files with an example the tag filter selects, one per line
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      # @raise [ConsoleCapture::Failure] when the list is stale, or the script refuses its arguments
+      def list_io_parallel_specs(**args)
+        { text: test_suite("list_io_parallel_specs", args) }
+      end
+
+      # @return [Hash] `text:` the expected match results of the pattern cases, as JSON
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def record_pattern_cases(**)
+        { 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
+      # @raise [Codebase::Tree::NeedsCheckout] when the tree is not a hecks checkout
+      def ir_constructs(**args)
+        { text: corpus("ir_constructs", args) }
+      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
+
+      # @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
+
+      private
+
+      def test_suite(operation, args)
+        tree.require_checkout!
+        plain_args = args.transform_values { |value| plain(value) }
+        Codebase::TestSuite.report(operation, plain_args, tree, shell: self.class.shell)
+      end
+
+      def corpus(operation, args)
+        tree.require_checkout!
+        plain_args = args.transform_values { |value| plain(value) }
+        Codebase::CorpusTasks.report(operation, plain_args, tree, shell: self.class.shell)
+      end
+
+      def report(operation, args)
+        tree.require_checkout!
+        plain_args = args.transform_values { |value| plain(value) }
+        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::Style, Codebase::Codemods, Codebase::TestSuite, Codebase::CorpusTasks, Codebase::Publishing].freeze
+      private_constant :FAMILIES
+
+      def tree = Codebase::Tree.new
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end