hecks 3.5.0 → 3.6.0

data/lib/hecks/release/runner.rb

@@ -7,6 +7,8 @@ require_relative "runner/tagger"
 require_relative "runner/gem_publisher"
 require_relative "runner/npm_publisher"
 require_relative "runner/ci_publisher"
+require_relative "runner/options"
+require_relative "runner/publishing"
 
 module Hecks
   module Release
@@ -16,100 +18,33 @@ module Hecks
     # Idempotent: it asks the registries what is already published and skips
     # it, so a run that died between the gem and the package resumes at the package.
     class Runner
-      # Which steps to run and how.
-      class Options
-        # @return [Boolean] run every check and build, but tag, push and publish nothing
-        attr_reader :dry_run
+      include Publishing
 
-        # @param dry_run [Boolean] run every check and build, but tag, push and publish nothing
-        # @param gem_only [Boolean] publish the gem, not the package
-        # @param npm_only [Boolean] do the npm step only, not the gem: wait for CI's publish, or
-        #   with `npm_local` publish from here
-        # @param npm_local [Boolean] publish the package from this machine, not by CI
-        # @param no_wait [Boolean] do not wait for CI's publish to reach npm
-        # @param yes [Boolean] answer every confirmation yes
-        # @raise [ArgumentError] if the flags contradict each other
-        def initialize(dry_run: false, gem_only: false, npm_only: false, npm_local: false, no_wait: false, yes: false)
-          check_flags(gem_only, npm_only, npm_local, no_wait)
-
-          @dry_run = dry_run
-          @gem_only = gem_only
-          @npm_only = npm_only
-          @npm_local = npm_local
-          @no_wait = no_wait
-          @yes = yes
-        end
-
-        # Says whether confirmations are answered automatically.
-        #
-        # @return [Boolean] true under `--yes`
-        def yes?
-          @yes
-        end
-
-        # Says whether the gem step is in scope.
-        #
-        # @return [Boolean] true unless `--npm-only`
-        def gem?
-          !@npm_only
-        end
-
-        # Says whether the npm step is in scope.
-        #
-        # @return [Boolean] true unless `--gem-only`
-        def npm?
-          !@gem_only
-        end
-
-        # Says whether the package is published from this machine.
-        #
-        # @return [Boolean] true under `--npm-local`
-        def npm_local?
-          @npm_local
-        end
-
-        # Says whether to wait for CI's publish to reach npm.
-        #
-        # @return [Boolean] true unless `--no-wait`
-        def wait?
-          !@no_wait
-        end
-
-        private
-
-        def check_flags(gem_only, npm_only, npm_local, no_wait)
-          raise ArgumentError, "--gem-only and --npm-only cannot be combined" if gem_only && npm_only
-          raise ArgumentError, "--gem-only and --npm-local cannot be combined" if gem_only && npm_local
-          return unless no_wait && npm_local
-
-          raise ArgumentError, "--no-wait applies to CI's publish, so it cannot be combined with --npm-local"
-        end
-      end
+      # The streams and clocks a run talks through, besides the ones a caller names.
+      ENVIRONMENT_KEYS = %i[input out err pause now].freeze
 
       # @param root [String] the repository root
       # @param options [Options] which steps to run and how
       # @param commands [#capture, #run!] starts every process the release runs
-      # @param input [IO] where confirmations are read from
-      # @param out [IO] where progress is written
-      # @param err [IO] where refusals and failures are written
-      # @param pause [#call] sleeps for a number of seconds while waiting for CI
-      # @param now [#call] answers the current time in seconds, monotonically, while waiting for CI
       # @param facts [Preflight::Facts, nil] what a caller already checked and cleared (a branch, a
       #   clean tree, matching versions, a changelog entry); the release then checks only that its
       #   tools are installed, and every rule stays with the caller
-      def initialize(root:, options: Options.new, commands: Commands.new, input: $stdin, out: $stdout, err: $stderr,
-                     pause: ->(seconds) { sleep(seconds) }, now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
-                     facts: nil)
+      # @param environment [Hash] any of: `input` (an IO confirmations are read from, `$stdin`),
+      #   `out` (where progress is written, `$stdout`), `err` (where refusals and failures are
+      #   written, `$stderr`), `pause` (sleeps for a number of seconds while waiting for CI) and
+      #   `now` (the current time in seconds, monotonically, while waiting for CI)
+      # @raise [ArgumentError] for any other keyword
+      def initialize(root:, options: Options.new, commands: Commands.new, facts: nil, **environment)
+        unknown = environment.keys - ENVIRONMENT_KEYS
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
         @root = root
         @facts = facts
         @steps = []
         @verified = false
         @options = options
         @commands = commands
-        @console = Console.new(input: input, out: out, err: err, assume_yes: options.yes?)
-        @git = Git.new(root: root, commands: commands)
-        @published = Published.new(root: root, commands: commands)
-        @ci = CiPublisher.new(root: root, published: @published, console: @console, pause: pause, now: now)
+        connect(default_environment.merge(environment))
       end
 
       # @return [Array<Symbol>] the steps this run carried out for real: `:tagged`, `:gem`, `:npm`
@@ -130,11 +65,7 @@ module Hecks
         # is what starts CI's npm publish.
         return declined unless @options.dry_run || pending.empty? || publish_confirmed?(facts.version, pending)
 
-        tagger = Tagger.new(git: @git, console: @console, dry_run: @options.dry_run)
-        return declined unless tagger.ensure!(facts, note: tag_note(facts.version, pending))
-
-        @steps << :tagged if tagger.changed?
-        publish(facts, pending)
+        tag_then_publish(facts, pending)
       rescue Refusal, CommandFailed => e
         @console.warn(e.message)
         1
@@ -142,6 +73,30 @@ module Hecks
 
       private
 
+      def default_environment
+        { input: $stdin, out: $stdout, err: $stderr, pause: ->(seconds) { sleep(seconds) },
+          now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) } }
+      end
+
+      def connect(environment)
+        @console = Console.new(input: environment[:input], out: environment[:out], err: environment[:err],
+                               assume_yes: @options.yes?)
+        @git = Git.new(root: @root, commands: @commands)
+        @published = Published.new(root: @root, commands: @commands)
+        @ci = CiPublisher.new(root: @root, published: @published, console: @console, pause: environment[:pause],
+                              now: environment[:now])
+      end
+
+      # @return [Integer] the exit status: the publish's, or 1 when the person declined the tag
+      #   question
+      def tag_then_publish(facts, pending)
+        tagger = Tagger.new(git: @git, console: @console, dry_run: @options.dry_run)
+        return declined unless tagger.ensure!(facts, note: tag_note(facts.version, pending))
+
+        @steps << :tagged if tagger.changed?
+        publish(facts, pending)
+      end
+
       def preflight
         check = Preflight.new(root: @root, commands: @commands, git: @git, tools: tools)
         return check.check! unless @facts
@@ -186,77 +141,6 @@ module Hecks
                        "publish it from here with --npm-local (the first publish, before trusted publishing is set up)"
       end
 
-      def publish(facts, pending)
-        if pending.empty?
-          @console.say("Nothing to publish for #{facts.version}.")
-          @verified = registries_list?(facts.version, in_scope) unless @options.dry_run
-          return 0
-        end
-        run_steps(facts.version, pending)
-      end
-
-      # What pushing the tag sets off, for the tag question; nothing when CI publishes nothing.
-      def tag_note(version, pending)
-        return unless ci_publishes?(pending)
-
-        "CI then publishes @hecks/client #{version} to npm from the tag, which cannot be undone"
-      end
-
-      def publish_confirmed?(version, pending)
-        targets = []
-        targets << "hecks #{version} to rubygems.org" if pending.include?(:gem)
-        targets << "@hecks/client #{version} to npm" if pending.include?(:npm) && @options.npm_local?
-        return true if targets.empty?
-
-        suffix = ci_publishes?(pending) ? " (CI then publishes @hecks/client from the tag)" : ""
-        @console.confirm?("Publish #{targets.join(' and ')}#{suffix}? This cannot be undone.")
-      end
-
-      def run_steps(version, pending)
-        dry_run = @options.dry_run
-        publish_gem(version, dry_run) if pending.include?(:gem)
-        return 1 if pending.include?(:npm) && !publish_npm!(version, dry_run, ci_publishes?(pending))
-
-        @verified = registries_list?(version, pending) unless dry_run
-
-        @console.say(dry_run ? "Dry run complete; nothing was tagged, pushed or published." : "Released hecks #{version}.")
-        0
-      end
-
-      def publish_gem(version, dry_run)
-        GemPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
-        @steps << :gem unless dry_run
-      end
-
-      # Asks each registry a step published to whether it now lists the version.
-      def registries_list?(version, pending)
-        (!pending.include?(:gem) || @published.gem?(version)) && (!pending.include?(:npm) || @published.npm?(version))
-      rescue Refusal
-        false
-      end
-
-      def publish_npm!(version, dry_run, via_ci)
-        return wait_for_ci!(version, dry_run) if via_ci
-
-        NpmPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
-        @steps << :npm unless dry_run
-        true
-      rescue CommandFailed => e
-        @console.warn("npm publish failed: #{e.message}")
-        unless dry_run
-          @console.warn("Finish the release with: hecks publish --npm-only --npm-local --confirm " \
-                        "(published steps are not repeated)")
-        end
-        raise
-      end
-
-      def wait_for_ci!(version, dry_run)
-        arrived = @ci.wait!(version, dry_run: dry_run, wait: @options.wait?)
-        @steps << :npm if arrived && !dry_run
-        @console.warn(CiPublisher.timeout_hint(version)) unless arrived
-        arrived
-      end
-
       def declined
         @console.warn("Aborted; nothing was published.")
         1

data/lib/hecks/rendering.rb

@@ -17,16 +17,20 @@ module Hecks
       case value
       when nil then "nil"
       when Hash, Array then JSON.generate(value)
-      else
-        # Duck-typed on `to_h`: naming Runtime::Value here would be circular, since
-        # it requires this file. A one-field wrapper unwraps to its bare scalar.
-        if value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
-          fields = value.to_h
-          fields.size == 1 ? describe(fields.values.first) : JSON.generate(fields)
-        else
-          value.inspect
-        end
+      else describe_other(value)
       end
     end
+
+    # Duck-typed on `to_h`: naming Runtime::Value here would be circular, since
+    # it requires this file. A one-field wrapper unwraps to its bare scalar.
+    #
+    # @param value [Object] anything but nil, a Hash or an Array
+    # @return [String] the value object's field or fields as described, or `value.inspect`
+    def describe_other(value)
+      return value.inspect unless value.respond_to?(:to_h)
+
+      fields = value.to_h
+      fields.size == 1 ? describe(fields.values.first) : JSON.generate(fields)
+    end
   end
 end

data/lib/hecks/router/door.rb

@@ -0,0 +1,37 @@
+require_relative "../doors/handle"
+
+module Hecks
+  class Router
+    class NamespaceInstaller
+      # One aggregate's repository and event log, read through its dispatcher.
+      Door = Struct.new(:dispatcher, :domain, :aggregate) do
+        # @param entry [Router::Entry] a router entry
+        # @return [Door, nil] the door for the entry's aggregate; nil for a query/command-only entry
+        #   whose owner isn't a real aggregate root
+        def self.for(entry)
+          domain = entry.fqn.domain
+          aggregate = entry.dispatcher.registry.bluebook(domain)&.aggregate(entry.fqn.aggregate)
+          new(entry.dispatcher, domain, aggregate) if aggregate
+        end
+
+        def repository = dispatcher.registry.repository(domain, aggregate)
+
+        def events
+          fqn = "#{domain}::#{aggregate.hecks_name}"
+          dispatcher.events.select { |event| event.aggregate == fqn }
+        end
+
+        def find(id)
+          found = repository.find(id)
+          found && handle(found)
+        end
+
+        def all = repository.all.map { |instance| handle(instance) }
+
+        def handle(instance)
+          Doors::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/router/namespace_installer.rb

@@ -1,48 +1,12 @@
 require_relative "../fqn"
-require_relative "../doors/handle"
+require_relative "options_proxy"
+require_relative "door"
 
 module Hecks
   class Router
     # Installs optional Ruby syntax over an already-loaded router; FQN
     # resolution stays in Router, this only adapts it to constants and methods.
     class NamespaceInstaller
-      # Returned by `.options(version:)`; forwards command/query verbs to the
-      # router, pinned to this FQN version rather than the router's default.
-      class OptionsProxy
-        # Only the `:version` keyword is accepted; any other key raises `ArgumentError`.
-        def initialize(router:, realm:, domain:, aggregate:, options:)
-          unknown = options.keys - [:version]
-          raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
-
-          @router = router
-          @realm = realm
-          @domain = domain
-          @aggregate = aggregate
-          @version = options[:version]&.to_s
-        end
-
-        def method_missing(verb, **args)
-          fqn = fqn_for(verb)
-          fqn.command? ? @router.dispatch(fqn.to_s, **args) : @router.query(fqn.to_s, **args)
-        end
-
-        def respond_to_missing?(verb, include_private = false)
-          Fqn.command_name?(verb) || Fqn.query_name?(verb) || super
-        end
-
-        private
-
-        def fqn_for(verb)
-          if Fqn.command_name?(verb)
-            Fqn.command(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, command: verb)
-          elsif Fqn.query_name?(verb)
-            Fqn.query(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, query: verb)
-          else
-            raise NoMethodError, "#{verb.inspect} is not a Bluebook command or query"
-          end
-        end
-      end
-
       def initialize(router)
         @router = router
       end
@@ -63,20 +27,26 @@ module Hecks
       def current_entries = router.available.reject { |entry| entry.fqn.version }
 
       def install_namespace_entry(entry)
-        target  = namespace_for(entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate)
-        address = entry.fqn.to_s
+        target = namespace_for(entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate)
+        define_options(target, entry.fqn)
+        define_verb(target, entry)
+      end
+
+      def define_options(target, fqn)
         active_router = router
         target.define_singleton_method(:options) do |**options|
-          OptionsProxy.new(router: active_router, realm: entry.fqn.realm, domain: entry.fqn.domain,
-                           aggregate: entry.fqn.aggregate, options: options)
-        end
-        if entry.command?
-          target.define_singleton_method(entry.fqn.verb) { |**args| active_router.dispatch(address, **args) }
-        else
-          target.define_singleton_method(entry.fqn.verb) { |**args| active_router.query(address, **args) }
+          OptionsProxy.new(router: active_router, realm: fqn.realm, domain: fqn.domain,
+                           aggregate: fqn.aggregate, options: options)
         end
       end
 
+      def define_verb(target, entry)
+        active_router = router
+        address = entry.fqn.to_s
+        route = entry.command? ? :dispatch : :query
+        target.define_singleton_method(entry.fqn.verb) { |**args| active_router.public_send(route, address, **args) }
+      end
+
       # `.find`/`.all`/`.count`/`.events`/`.repository`, matching `Hecks.boot`'s
       # door; grouped by (realm, domain, aggregate) since the five don't vary by verb.
       def install_aggregate_doors!
@@ -86,43 +56,35 @@ module Hecks
       end
 
       def install_aggregate_door(entry)
-        dispatcher = entry.dispatcher
-        domain     = entry.fqn.domain
-        ir         = dispatcher.registry.bluebook(domain)&.aggregate(entry.fqn.aggregate)
-        return unless ir # a query/command-only entry whose owner isn't a real aggregate root
-
-        fqn    = "#{domain}::#{ir.hecks_name}"
-        target = namespace_for(entry.fqn.realm, domain, entry.fqn.aggregate)
+        door = Door.for(entry)
+        return unless door
 
-        target.define_singleton_method(:repository) { dispatcher.registry.repository(domain, ir) }
-        target.define_singleton_method(:count)      { dispatcher.registry.repository(domain, ir).count }
-        target.define_singleton_method(:events)     { dispatcher.events.select { |event| event.aggregate == fqn } }
-
-        target.define_singleton_method(:find) do |id|
-          found = dispatcher.registry.repository(domain, ir).find(id)
-          found && Doors::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: found)
-        end
+        define_door_methods(namespace_for(entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate), door)
+      end
 
-        target.define_singleton_method(:all) do
-          dispatcher.registry.repository(domain, ir).all.map do |instance|
-            Doors::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: instance)
-          end
-        end
+      def define_door_methods(target, door)
+        target.define_singleton_method(:repository) { door.repository }
+        target.define_singleton_method(:count)      { door.repository.count }
+        target.define_singleton_method(:events)     { door.events }
+        target.define_singleton_method(:find)       { |id| door.find(id) }
+        target.define_singleton_method(:all)        { door.all }
       end
 
       def install_shortcuts!
-        installer = self
         current_entries.reject { |entry| entry.fqn.aggregate.nil? }
                        .group_by { |entry| [entry.fqn.aggregate, entry.fqn.verb] }
-                       .each do |(aggregate, verb), candidates|
-          # Bounded chapters wrap in their own module (`Domain::Aggregate`) so two
-          # BCs can both declare `Person` without colliding on `Object::Person`.
-          # Folder-spread files of the same chapter aren't BCs, so they still get it.
-          next if bounded_chapter?(candidates)
-
-          shortcut_target(aggregate).define_singleton_method(verb) do |**args|
-            installer.send(:dispatch_short, candidates, **args)
-          end
+                       .each { |(aggregate, verb), candidates| install_shortcut(aggregate, verb, candidates) }
+      end
+
+      def install_shortcut(aggregate, verb, candidates)
+        # Bounded chapters wrap in their own module (`Domain::Aggregate`) so two
+        # BCs can both declare `Person` without colliding on `Object::Person`.
+        # Folder-spread files of the same chapter aren't BCs, so they still get it.
+        return if bounded_chapter?(candidates)
+
+        installer = self
+        shortcut_target(aggregate).define_singleton_method(verb) do |**args|
+          installer.send(:dispatch_short, candidates, **args)
         end
       end
 
@@ -131,17 +93,17 @@ module Hecks
       end
 
       def dispatch_short(candidates, **args)
-        if candidates.length > 1
-          shown = candidates.map { |entry| entry.fqn.to_s }.sort.join(", ")
-          aggregate = candidates.first.fqn.aggregate
-          verb = candidates.first.fqn.verb
-          raise AmbiguousShortRoute, "#{aggregate}.#{verb} is ambiguous — choose one of: #{shown}"
-        end
+        raise AmbiguousShortRoute, ambiguity_message(candidates) if candidates.length > 1
 
         entry = candidates.fetch(0)
         entry.command? ? router.dispatch(entry.fqn.to_s, **args) : router.query(entry.fqn.to_s, **args)
       end
 
+      def ambiguity_message(candidates)
+        shown = candidates.map { |entry| entry.fqn.to_s }.sort.join(", ")
+        "#{candidates.first.fqn.aggregate}.#{candidates.first.fqn.verb} is ambiguous — choose one of: #{shown}"
+      end
+
       def shortcut_target(aggregate)
         constant = Object.const_get(aggregate, false) if Object.const_defined?(aggregate, false)
         if constant && !constant.is_a?(Module)

data/lib/hecks/router/options_proxy.rb

@@ -0,0 +1,44 @@
+require_relative "../fqn"
+
+module Hecks
+  class Router
+    class NamespaceInstaller
+      # Returned by `.options(version:)`; forwards command/query verbs to the
+      # router, pinned to this FQN version rather than the router's default.
+      class OptionsProxy
+        # Only the `:version` keyword is accepted; any other key raises `ArgumentError`.
+        def initialize(router:, realm:, domain:, aggregate:, options:)
+          unknown = options.keys - [:version]
+          raise ArgumentError, "unknown router options: #{unknown.join(", ")}" unless unknown.empty?
+
+          @router = router
+          @realm = realm
+          @domain = domain
+          @aggregate = aggregate
+          @version = options[:version]&.to_s
+        end
+
+        def method_missing(verb, **args)
+          fqn = fqn_for(verb)
+          fqn.command? ? @router.dispatch(fqn.to_s, **args) : @router.query(fqn.to_s, **args)
+        end
+
+        def respond_to_missing?(verb, include_private = false)
+          Fqn.command_name?(verb) || Fqn.query_name?(verb) || super
+        end
+
+        private
+
+        def fqn_for(verb)
+          if Fqn.command_name?(verb)
+            Fqn.command(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, command: verb)
+          elsif Fqn.query_name?(verb)
+            Fqn.query(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, query: verb)
+          else
+            raise NoMethodError, "#{verb.inspect} is not a Bluebook command or query"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/adapter_lookup.rb

@@ -59,7 +59,7 @@ module Hecks
         when 0 then raise WiringError, "no adapter implements the #{port_name} port — nothing can answer #{asked}"
         else raise WiringError,
                    "#{implementations.size} adapters implement the #{port_name} port " \
-                   "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+                   "(#{implementations.map(&:name).sort.join(", ")}) — the runtime will not choose for you"
         end
       end
 
@@ -76,48 +76,69 @@ module Hecks
       # @raise [Runtime::WiringError] if the constructor needs arguments, the method is missing or
       #   inherited, or its keywords do not match the query's arguments
       def check_answers!(klass, port_name, method, query, asked:)
+        check_buildable!(klass, port_name)
+        check_defined!(klass, port_name, method, asked)
+        check_keywords!(klass, method, query, asked)
+      end
+
+      # @raise [Runtime::WiringError] if the constructor requires arguments
+      def check_buildable!(klass, port_name)
         required = klass.instance_method(:initialize).parameters.filter_map { |kind, name| name if %i[req keyreq].include?(kind) }
-        unless required.empty?
-          raise WiringError, "#{klass} implements the #{port_name} port but its constructor requires " \
-                             "#{required.join(', ')} — it is built with no arguments"
-        end
+        return if required.empty?
 
-        unless klass.public_method_defined?(method) &&
-               !INHERITED_OWNERS.include?(klass.public_instance_method(method).owner)
-          raise WiringError, "#{klass} implements the #{port_name} port but not ##{method}, " \
-                             "which answers #{asked}"
-        end
+        raise WiringError, "#{klass} implements the #{port_name} port but its constructor requires " \
+                           "#{required.join(", ")} — it is built with no arguments"
+      end
 
-        check_keywords!(klass, method, query, asked)
+      # @raise [Runtime::WiringError] if the method is missing or only inherited
+      def check_defined!(klass, port_name, method, asked)
+        return if klass.public_method_defined?(method) &&
+                  !INHERITED_OWNERS.include?(klass.public_instance_method(method).owner)
+
+        raise WiringError, "#{klass} implements the #{port_name} port but not ##{method}, " \
+                           "which answers #{asked}"
       end
 
       # @raise [Runtime::WiringError] if the method takes a positional argument, requires a keyword
       #   the query does not require, or accepts none of a declared argument
       def check_keywords!(klass, method, query, asked)
+        wanted     = query_keywords(query)
         parameters = klass.public_instance_method(method).parameters
-        wanted     = query.attributes.map { |attribute| attribute.name.to_sym }
-        required   = query.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym }
-        problems   = keyword_problems(parameters, wanted, required)
+        problems   = keyword_problems(parameters, wanted, query_keywords(query, required: true))
         return if problems.empty?
 
-        raise WiringError, "#{klass}##{method} answers #{asked} but #{problems.join(' and ')} — it is asked " \
-                           "with keywords for the query's arguments (#{wanted.empty? ? 'none' : wanted.join(', ')})"
+        raise WiringError, "#{klass}##{method} answers #{asked} but #{problems.join(" and ")} — it is asked " \
+                           "with keywords for the query's arguments (#{wanted.empty? ? "none" : wanted.join(", ")})"
+      end
+
+      # @return [Array<Symbol>] the query's argument names, only the required ones if `required`
+      def query_keywords(query, required: false)
+        attributes = required ? query.attributes.reject(&:optional?) : query.attributes
+        attributes.map { |attribute| attribute.name.to_sym }
       end
 
       # @return [Array<String>] how `parameters` fails to take exactly the `wanted` keywords
       def keyword_problems(parameters, wanted, required)
-        kinds   = parameters.map(&:first)
-        taken   = parameters.select { |kind, _| kind.to_s.start_with?("key") && kind != :keyrest }.map(&:last)
-        missing = kinds.include?(:keyrest) ? [] : wanted - taken
-        extra   = parameters.select { |kind, name| kind == :keyreq && !required.include?(name) }.map(&:last)
-        [("takes positional arguments" if kinds.intersect?(%i[req opt rest])),
-         keyword_problem("does not take", missing),
-         keyword_problem("requires", extra, ", which the query does not")].compact
+        [("takes positional arguments" if parameters.map(&:first).intersect?(%i[req opt rest])),
+         keyword_problem("does not take", missing_keywords(parameters, wanted)),
+         keyword_problem("requires", extra_keywords(parameters, required), ", which the query does not")].compact
+      end
+
+      # @return [Array<Symbol>] the wanted keywords the parameters do not take
+      def missing_keywords(parameters, wanted)
+        return [] if parameters.any? { |kind, _| kind == :keyrest }
+
+        wanted - parameters.select { |kind, _| kind.to_s.start_with?("key") && kind != :keyrest }.map(&:last)
+      end
+
+      # @return [Array<Symbol>] the required keywords the query does not require
+      def extra_keywords(parameters, required)
+        parameters.select { |kind, name| kind == :keyreq && !required.include?(name) }.map(&:last)
       end
 
       # @return [String, nil] a phrase naming `names` as keywords, or nil when there are none
       def keyword_problem(verb, names, suffix = "")
-        "#{verb} #{names.map { |name| "#{name}:" }.join(', ')}#{suffix}" unless names.empty?
+        "#{verb} #{names.map { |name| "#{name}:" }.join(", ")}#{suffix}" unless names.empty?
       end
     end
   end