hecks 2.9.0 → 3.0.0

data/lib/hecks/grammar/evolve.rb

@@ -0,0 +1,336 @@
+module Hecks
+  module Grammar
+    # File surgery under `hecks word_status` and its siblings: reads and rewrites the
+    # aggregate-local KeywordSeed/ArgumentSeed rows as text, preserving the table's own formatting.
+    module Evolve
+      class Refusal < StandardError; end
+
+      module_function
+
+      # Only consumes the next argv element as the value when it isn't itself
+      # a flag, so `--foo --bar` doesn't swallow `--bar` as `--foo`'s value.
+      def option(argv, name, default = nil)
+        index = argv.index("--#{name}")
+        return default unless index
+
+        value = argv[index + 1]
+        value.nil? || value.start_with?("-") ? default : value
+      end
+
+      # Runs the block against an in-memory copy of the tables: every edit it makes is held, none
+      # is written, and later reads see the earlier edits.
+      #
+      # @yield the edits to rehearse
+      # @return [Hash{String => String}] each file the edits changed, with the text it would hold
+      def rehearse
+        @overlay = {}
+        yield
+        @overlay.dup
+      ensure
+        @overlay = nil
+      end
+
+      # @param path [String] a table file
+      # @return [String] its text: a rehearsed edit if one was made, else what the file holds
+      def read_source(path)
+        @overlay&.key?(path) ? @overlay[path] : File.read(path)
+      end
+
+      # @param path [String] a table file
+      # @param text [String] what it holds afterwards; held, not written, while rehearsing
+      # @return [Object] the text
+      def write_source(path, text)
+        @overlay ? (@overlay[path] = text) : File.write(path, text)
+      end
+
+      # Snapshots `paths` before running the block and restores every file
+      # if it raises, even partway through a multi-file write.
+      def restore_on_raise(paths)
+        snapshots = paths.to_h { |path| [path, File.read(path)] }
+        yield
+      rescue StandardError
+        snapshots.each { |path, content| File.write(path, content) }
+        raise
+      end
+
+      # Every syntax-table file declaring a KeywordSeed or ArgumentSeed value object.
+      def syntax_paths
+        Dir.glob(File.expand_path("../language/**/*.bluebook", __dir__)).select do |path|
+          source = read_source(path)
+          source.include?('value_object "KeywordSeed"') || source.include?('value_object "ArgumentSeed"')
+        end
+      end
+
+      # Narrow compatibility door for single-file callers; syntax_paths is normal.
+      def syntax_path = syntax_paths.first
+
+      # Resolves the file(s) a call should search or write.
+      def paths_for(path) = path ? Array(path) : syntax_paths
+
+      # Parses the Keyword one_of's member rows leniently off the text.
+      def keyword_rows(path = nil)
+        paths_for(path).flat_map do |candidate|
+          blocks = seed_blocks(read_source(candidate), "KeywordSeed")
+          raise Refusal, "source declares no KeywordSeed value object" if path && blocks.empty?
+
+          blocks.flat_map do |block|
+            block.scan(/^\s*member (.+)$/).map do |(cells)|
+              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
+              { word: row["word"], context: row["context"],
+                status: row.fetch("status", "admitted"), was: row["was"] }
+            end
+          end
+        end
+      end
+
+      # Declares a new, proposed keyword row in the syntax table that owns
+      # `context` (or the aggregate `opens` names, for a File-context word).
+      def propose(word:, context:, body: "none", inner: "", opens: "", fills: "", path: nil)
+        if keyword_rows(path).any? do |row|
+          row[:word] == word && row[:context] == context
+        end
+          raise Refusal,
+                "#{context}.#{word} is already declared — one row per (word, context, form)"
+        end
+
+        path = owner_path(context: context, word: word, opens: opens, paths: paths_for(path))
+        source = read_source(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.include?(%(context: "#{context}")) } || keyword_block(source)
+        indent = block[/^(\s*)member /, 1] || "        "
+        row = %(#{indent}member word: "#{word}", context: "#{context}", body: "#{body}", ) +
+              %(inner: "#{inner}", opens: "#{opens}", fills: "#{fills}", status: "proposed"\n)
+
+        # Appended at the end; whoever admits it may move it to its group.
+        closing = block.rindex(/^\s*end\s*$/)
+        updated = block[0...closing] + row + block[closing..]
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Rewrites a declared keyword row's status: cell in place.
+      def set_status(word:, context:, to:, path: nil)
+        raise Refusal, "#{to.inspect} is not a station a word's life admits" unless %w[proposed admitted deprecated
+                                                                                       retired].include?(to)
+
+        path = path_holding_keyword(word, context, paths_for(path))
+        source = read_source(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
+        rows   = block.lines.select { |line| member_row?(line, word, context) }
+        raise Refusal, "#{context}.#{word} is not declared" if rows.empty?
+
+        updated = block.lines.map do |line|
+          next line unless member_row?(line, word, context)
+
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          # Admitted is the default and stays unspelled in the row.
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        end.join
+
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Respells a keyword row (was: holds the old spelling) — one hop only;
+      # its Argument rows follow, row-aware (see cascade_argument_rename).
+      def rename(word:, context:, to:, path: nil)
+        row = keyword_rows(path).find { |r| r[:word] == word && r[:context] == context }
+        raise Refusal, "#{context}.#{word} is not declared" unless row
+        raise Refusal, "#{context}.#{word} was already #{row[:was]} — one rename hop, then eras" if row[:was]
+        if keyword_rows(path).any? do |r|
+          r[:word] == to && r[:context] == context
+        end
+          raise Refusal,
+                "#{context}.#{to} is already declared — a rename cannot land on a living word"
+        end
+
+        paths = paths_for(path)
+        path = path_holding_keyword(word, context, paths)
+        source = read_source(path)
+        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
+        updated = block.lines.map do |line|
+          next line unless member_row?(line, word, context)
+
+          line.sub(%(word: "#{word}"), %(word: "#{to}"))
+              .sub(/\n\z/, %(, was: "#{word}"\n))
+        end.join
+        source = source.sub(block, updated)
+        write_source(path, source)
+
+        cascade_argument_rename(keyword: word, context: context, to: to, path: paths)
+      end
+
+      # Tells whether `line` is a KeywordSeed member row for (word, context).
+      def member_row?(line, word, context)
+        line =~ /^\s*member / && line.include?(%(word: "#{word}")) && line.include?(%(context: "#{context}"))
+      end
+
+      # Finds which syntax-table path declares a keyword row.
+      def path_holding_keyword(word, context, paths = syntax_paths)
+        paths.find do |candidate|
+          keyword_blocks(read_source(candidate)).any? { |block| block.lines.any? { |line| member_row?(line, word, context) } }
+        end || raise(Refusal, "#{context}.#{word} is not declared")
+      end
+
+      # Finds which syntax-table path declares an argument row.
+      def path_holding_argument(keyword, context, at, named, paths = syntax_paths)
+        paths.find do |candidate|
+          argument_blocks(read_source(candidate)).any? do |block|
+            block.lines.any? do |line|
+              argument_row?(line, keyword, context, at, named)
+            end
+          end
+        end || raise(Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not declared")
+      end
+
+      # Picks the owning file for a new row; opens names the aggregate for a File-context word.
+      def owner_path(context:, word:, opens: "", paths: syntax_paths)
+        if context == "File" && !opens.to_s.empty?
+          aggregate_path = paths.find { |candidate| read_source(candidate).match?(/^\s*aggregate "#{Regexp.escape(opens)}" do$/) }
+          return aggregate_path if aggregate_path
+        end
+
+        paths.find do |candidate|
+          source = read_source(candidate)
+          %w[KeywordSeed ArgumentSeed].any? do |seed|
+            seed_blocks(source, seed).any? { |block| block.include?(%(context: "#{context}")) }
+          end
+        end || raise(Refusal, "no aggregate-local syntax table owns context #{context.inspect} for #{word}")
+      end
+
+      # Every value_object "<name>" block's full source text, opener to closing end.
+      def seed_blocks(source, name)
+        opener = /^([ \t]*)value_object "#{Regexp.escape(name)}" do$/
+        source.to_enum(:scan, opener).map do
+          match = Regexp.last_match
+          start = match.begin(0)
+          indent = match[1]
+          closing = source.index(/^#{Regexp.escape(indent)}end\s*$/, match.end(0))
+          closing = source.index(/\n/, closing) + 1
+          source[start...closing]
+        end
+      end
+
+      # The first value_object "<name>" block's source text.
+      def seed_block(source, name, required: false)
+        block = seed_blocks(source, name).first
+        unless block
+          raise Refusal, "source declares no #{name} value object" if required
+
+          return
+        end
+        block
+      end
+
+      # First `end` after the opener is the block's own — member rows sit bare (ADR 0025).
+      def keyword_blocks(source) = seed_blocks(source, "KeywordSeed")
+
+      # The first KeywordSeed block's source text.
+      def keyword_block(source) = seed_block(source, "KeywordSeed", required: true)
+
+      # Parses the ArgumentSeed's member rows leniently off the text.
+      def argument_rows(path = nil)
+        paths_for(path).flat_map do |candidate|
+          blocks = seed_blocks(read_source(candidate), "ArgumentSeed")
+          raise Refusal, "source declares no ArgumentSeed value object" if path && blocks.empty?
+
+          blocks.flat_map do |block|
+            block.scan(/^\s*member (.+)$/).map do |(cells)|
+              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
+              { keyword: row["keyword"], context: row["context"], at: row["at"].to_s,
+                named: row["named"].to_s, kind: row["kind"], required: row["required"],
+                fills: row["fills"].to_s, status: row.fetch("status", "admitted") }
+            end
+          end
+        end
+      end
+
+      # Declares a new, proposed argument row; pairs_shape marks a `pairs`
+      # argument that fills a whole key/value list, not a single field.
+      def propose_argument(keyword:, context:, kind:, required: "false", at: "", named: "", fills: "",
+                           pairs_shape: nil, path: nil)
+        if argument_rows(path).any? { |r| argument_identity(r) == [keyword, context, at, named] }
+          raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is " \
+                         "already declared — one row per (keyword, context, at, named)"
+        end
+
+        path = owner_path(context: context, word: keyword, paths: paths_for(path))
+        source = read_source(path)
+        block  = argument_blocks(source).find do |candidate|
+          candidate.include?(%(context: "#{context}"))
+        end || argument_block(source)
+        indent = block[/^(\s*)member /, 1] || "        "
+        shape = pairs_shape.to_s.empty? ? "" : %(pairs_shape: "#{pairs_shape}", )
+        row = %(#{indent}member keyword: "#{keyword}", context: "#{context}", at: "#{at}", ) +
+              %(named: "#{named}", kind: "#{kind}", required: "#{required}", fills: "#{fills}", ) +
+              shape + %(status: "proposed"\n)
+
+        closing = block.rindex(/^\s*end\s*$/)
+        updated = block[0...closing] + row + block[closing..]
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Rewrites a declared argument row's status: cell in place.
+      def set_argument_status(keyword:, context:, to:, at: "", named: "", path: nil)
+        raise Refusal, "#{to.inspect} is not a station an argument's life admits" unless %w[proposed admitted deprecated
+                                                                                            retired].include?(to)
+
+        path = path_holding_argument(keyword, context, at, named, paths_for(path))
+        source = read_source(path)
+        block  = argument_blocks(source).find do |candidate|
+          candidate.lines.any? do |line|
+            argument_row?(line, keyword, context, at, named)
+          end
+        end
+        rows = block.lines.select { |line| argument_row?(line, keyword, context, at, named) }
+        if rows.empty?
+          raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not " \
+                         "declared"
+        end
+
+        updated = block.lines.map do |line|
+          next line unless argument_row?(line, keyword, context, at, named)
+
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        end.join
+
+        write_source(path, source.sub(block, updated))
+      end
+
+      # Tells whether `line` is an ArgumentSeed row for this (keyword, context, at, named) tuple.
+      def argument_row?(line, keyword, context, at, named)
+        line =~ /^\s*member / &&
+          line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}")) &&
+          line.include?(%(at: "#{at}")) && line.include?(%(named: "#{named}"))
+      end
+
+      # The (keyword, context, at, named) identity tuple an argument row is keyed
+      # by — wider than a Keyword row's two-field key.
+      def argument_identity(row) = [row[:keyword], row[:context], row[:at], row[:named]]
+
+      # Row-aware rename cascade — updates only the argument rows that belong
+      # to the renamed keyword, not a blind gsub across the file.
+      def cascade_argument_rename(keyword:, context:, to:, path: nil)
+        paths_for(path).each do |candidate|
+          source = read_source(candidate)
+          original = source
+          argument_blocks(source).each do |block|
+            updated = block.lines.map do |line|
+              next line unless line =~ /^\s*member / &&
+                               line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}"))
+
+              line.sub(%(keyword: "#{keyword}"), %(keyword: "#{to}"))
+            end.join
+            source = source.sub(block, updated) if updated != block
+          end
+          write_source(candidate, source) if source != original
+        end
+      end
+
+      # ArgumentSeed blocks; see keyword_blocks for why the first bare end
+      # after the opener is already the block's own.
+      def argument_blocks(source) = seed_blocks(source, "ArgumentSeed")
+
+      # The first ArgumentSeed block's source text.
+      def argument_block(source) = seed_block(source, "ArgumentSeed", required: true)
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "ruby_child"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `CodemodRun` asks of the working tree: the mechanical rewrites of the
+      # example bluebooks.
+      #
+      # Each codemod is a script built on `Hecks::Codemod` (`lib/hecks/codemod.rb`), which reboots
+      # every bluebook it edits and puts the file back when the rewrite changes what the bluebook
+      # means. The script runs in a child process from the checkout's root. Unconfirmed it runs
+      # with `--dry-run`, which restores every file it touched, so tracked files stay changed only
+      # when the request is confirmed.
+      module Codemods
+        # Every operation this family carries out.
+        OPERATIONS = %w[hoist_local_givens drop_implicit_append_fields].freeze
+
+        # The script each operation runs.
+        SCRIPTS = { "hoist_local_givens"          => "codemod_hoist_local_givens",
+                    "drop_implicit_append_fields" => "codemod_implicit_append_fields" }.freeze
+
+        module_function
+
+        # Carries out one codemod.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `CodemodRun` record's fields: `confirm`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused: the codemod runs in this process
+        # @return [String] what the script found for each example, and whether it rewrote it
+        # @raise [ConsoleCapture::Failure] when the script ends badly
+        def call(operation, held, tree, shell: nil)
+          confirm = held[:confirm].is_a?(Hash) ? held[:confirm][:value] : held[:confirm]
+          child = RubyChild.new(tree)
+          return child.answer(SCRIPTS.fetch(operation)) if confirm == true
+
+          "dry run, nothing kept (add --confirm to rewrite):\n#{child.answer(SCRIPTS.fetch(operation), '--dry-run')}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "ruby_child"
+require "hecks/engine_agreement"
+require "hecks/doc/reference"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `ConformanceRun` asks of the working tree: the checks on the language
+      # itself.
+      #
+      # The query-engine check and the reference-docs check read the tree in this process, with the
+      # code the verbs run elsewhere, and write nothing. The argument-gate matrix boots several
+      # throwaway domains and replays them, so it runs in a child process; without `confirm` the
+      # script only reports, and with it the script rewrites the committed matrix and its fixtures.
+      module Conformance
+        # Every operation this family carries out.
+        OPERATIONS = %w[check_engine_agreement measure_doc_coverage argument_gate_matrix].freeze
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `ConformanceRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @return [String] what the check found
+        # @raise [ConsoleCapture::Failure] when the check finds a disagreement
+        def call(operation, held, tree, shell: nil)
+          case operation
+          when "check_engine_agreement" then engine_agreement(tree)
+          when "measure_doc_coverage" then doc_coverage(tree)
+          else gate_matrix(held, tree)
+          end
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] the clean verdict
+        # @raise [ConsoleCapture::Failure] with every problem, when the engines disagree
+        def engine_agreement(tree)
+          finding = EngineAgreement.check(root: tree.root)
+          return EngineAgreement.clean_line(finding) if finding.problems.empty?
+
+          raise ConsoleCapture::Failure, EngineAgreement.problem_lines(finding)
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] the clean verdict
+        # @raise [ConsoleCapture::Failure] with each word that lacks prose or an example
+        def doc_coverage(tree)
+          clean, report = Doc::Reference.coverage_report(tree.path("docs/implemented/reference"))
+          raise ConsoleCapture::Failure, report unless clean
+
+          report
+        end
+
+        # @param held [Hash] the record's fields; `confirm` makes the script write
+        # @param tree [Tree] the checkout
+        # @return [String] what the script printed: the rows kept and dropped, and what it wrote
+        # @raise [ConsoleCapture::Failure] when the script ends badly
+        def gate_matrix(held, tree)
+          confirm = held[:confirm].is_a?(Hash) ? held[:confirm][:value] : held[:confirm]
+          child = RubyChild.new(tree)
+          child.answer("argument_gate_matrix", *("--write" if confirm == true))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "hecks/corpus"
+require "hecks/query_ir"
+require "hecks/query_ir_mcp"
+require_relative "tree"
+require "hecks/rust_build"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `CorpusRun` asks of the working tree: which committed domains have a Rust
+      # feature, what the language's IR holds, and the two doors that serve it.
+      #
+      # The questions are pure reads and run in this process, with the code `hecks rust_domains` and
+      # `hecks ir_constructs` run (`Hecks::Corpus`, `Hecks::QueryIR`); the coverage question runs
+      # `Hecks::RustBuild`'s coverage tool over each generated module, also in this process. The
+      # two doors run until they are closed: the query MCP server on stdio, and the forms app on a
+      # local port.
+      module CorpusTasks
+        # Every operation this family carries out.
+        OPERATIONS = %w[serve_query_ir_mcp present].freeze
+
+        # The port `present` listens on when none is named.
+        DEFAULT_PORT = 4567
+
+        class << self
+          # @return [#call, nil] serves the MCP door; `Hecks::QueryIrMcp.start` when nil. A spec
+          #   replaces it so no stdio has to be held.
+          attr_accessor :mcp_server
+
+          # @return [#call, nil] takes `app:` and `port:` and serves until stopped; a WEBrick
+          #   server through Rack when nil.
+          attr_accessor :web_server
+
+          # @return [#capture, nil] runs each coverage check, as `capture(tool, argv, env:)`
+          #   answering an object with `out`, `err` and `ok?`; `Hecks::RustBuild` when nil.
+          attr_accessor :coverage_runner
+        end
+
+        module_function
+
+        # Opens one of the doors.
+        #
+        # @param operation [String] `serve_query_ir_mcp` or `present`
+        # @param held [Hash] the `CorpusRun` record's fields: `port`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused
+        # @return [String] a note that the door closed
+        # @raise [ConsoleCapture::Failure] when the MCP door refuses the process's setup
+        def call(operation, held, tree, shell: nil)
+          _ = shell
+          return serve_mcp if operation == "serve_query_ir_mcp"
+
+          present(plain(held)[:port] || DEFAULT_PORT, tree)
+        end
+
+        # A pure read.
+        #
+        # @param operation [String] a query's name in snake case
+        # @param args [Hash] the query's plain arguments
+        # @param tree [Tree] the checkout
+        # @param shell [#capture, nil] unused; the coverage checks run in this process
+        # @return [String] the answer, one line for each row
+        # @raise [ConsoleCapture::Failure] when a coverage check fails, or a query is refused
+        def report(operation, args, tree, shell: nil)
+          _ = shell
+          case operation
+          when "rust_domains" then rust_domains(tree)
+          when "regen_order" then regen_order(tree)
+          when "corpus_rust_coverage" then coverage(tree)
+          else ir_query(operation, args)
+          end
+        end
+
+        # @param held [Hash] fields, each perhaps a value object's `{ value: x }`
+        # @return [Hash] the same fields as plain values
+        def plain(held) = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+
+        # @return [String] a note that the MCP door closed
+        # @raise [ConsoleCapture::Failure] when the door refuses to start
+        def serve_mcp
+          server = CorpusTasks.mcp_server || ->(**options) { QueryIrMcp.start(**options) }
+          server.call(argv: [])
+          "query ir mcp door closed"
+        rescue SystemExit => e
+          raise ConsoleCapture::Failure, "the query ir mcp door refused to start (status #{e.status}); see stderr"
+        end
+
+        # @param port [Integer] the port to listen on
+        # @param tree [Tree] the checkout
+        # @return [String] a note that the server stopped
+        def present(port, tree)
+          require "hecks/forms/banking_presentation"
+          app = Forms::BankingPresentation.app(root: tree.root)
+          warn "banking forms, in memory, on http://localhost:#{port}/ - no authentication, no CSRF " \
+               "protection, no caller identity; do not expose beyond localhost"
+          (CorpusTasks.web_server || method(:rack_serve)).call(app: app, port: port)
+          "presented on port #{port}, now stopped"
+        end
+
+        # @param app [#call] the Rack app
+        # @param port [Integer] the port
+        # @return [void]
+        def rack_serve(app:, port:)
+          require "rackup"
+          Rackup::Server.start(app: app, Port: port, server: "webrick")
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] each domain with a Rust feature: its feature, a tab, and its directory
+        def rust_domains(tree)
+          Corpus.rust_domains(root: tree.root).map { |domain| "#{domain.feature}\t#{tree.relative(domain.dir)}" }
+                .join("\n")
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] the directories regeneration walks, in order, one for each line
+        def regen_order(tree)
+          Corpus.rust_regen_order(root: tree.root).map { |domain| tree.relative(domain.dir) }.join("\n")
+        end
+
+        # Runs the coverage tool over every generated module. A module named in
+        # `Corpus::RUST_COVERAGE_PENDING` must still fail; every other one must pass.
+        #
+        # @param tree [Tree] the checkout
+        # @return [String] one line for each module, and how many were checked
+        # @raise [ConsoleCapture::Failure] with every module that failed, or that passes now while
+        #   still listed as pending
+        def coverage(tree)
+          modules = Corpus.generated_modules(root: tree.root)
+          pending = Corpus::RUST_COVERAGE_PENDING
+          unknown = pending.keys - modules
+          raise ConsoleCapture::Failure, "pending names #{unknown.join(', ')}, with no generated module" if unknown.any?
+
+          lines, problems = judge(modules, pending, coverage_results(modules, tree))
+          raise ConsoleCapture::Failure, [*lines, "", *problems].join("\n") if problems.any?
+
+          [*lines, "#{modules.size} generated modules checked"].join("\n")
+        end
+
+        # @param modules [Array<String>] the generated modules
+        # @param pending [Hash{String => String}] the modules known to fail, and why
+        # @param results [Hash{String => Array}] each module's `[passed, output]`
+        # @return [Array(Array<String>, Array<String>)] the report lines and the problems
+        def judge(modules, pending, results)
+          problems = []
+          lines = modules.map do |name|
+            passed, output = results.fetch(name)
+            if pending.key?(name)
+              problems << "#{name} passes now - delete it from Hecks::Corpus::RUST_COVERAGE_PENDING" if passed
+              "#{name}: pending (#{passed ? 'NOW PASSES' : 'still fails'}) - #{pending[name]}"
+            else
+              problems << "#{name} failed:\n#{output}" unless passed
+              "#{name}: #{passed ? 'ok' : 'FAILED'}"
+            end
+          end
+          [lines, problems]
+        end
+
+        # @param modules [Array<String>] the generated modules
+        # @param tree [Tree] the checkout
+        # @return [Hash{String => Array}] each module's `[passed, output]`
+        def coverage_results(modules, tree)
+          runner = CorpusTasks.coverage_runner || RustBuild
+          env = { "HECKS_RUST_DIR" => tree.path("rust") }
+          modules.to_h do |name|
+            result = runner.capture("rust_coverage", [name], env: env)
+            [name, [result.ok?, [result.out, result.err].join]]
+          end
+        end
+
+        # @param operation [String] `ir_constructs`, `ir_duplicates` or `ir_impact`
+        # @param args [Hash] the query's plain arguments
+        # @return [String] the formatted answer
+        # @raise [ConsoleCapture::Failure] when the query refuses its arguments
+        def ir_query(operation, args)
+          case operation
+          when "ir_constructs" then QueryIR.format_constructs(QueryIR.constructs(words(args[:names])))
+          when "ir_duplicates" then duplicates(args)
+          else QueryIR.format_impact_preview(QueryIR.impact_preview(args[:name], args[:field]))
+          end
+        rescue ArgumentError => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @param args [Hash] `domains` and `meta`
+        # @return [String] the duplicated rules; the meta-domain is included when asked for, or
+        #   when no domain is named
+        def duplicates(args)
+          domains = args[:domains] ? words(args[:domains]) : nil
+          QueryIR.format_duplicates(QueryIR.duplicates(domains: domains, include_meta: args[:meta] == true || domains.nil?))
+        end
+
+        # @param list [String, nil] a comma-separated list
+        # @return [Array<String>] its items
+        def words(list) = list.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end