hecks 2.9.0 → 3.0.1

data/lib/hecks/release/runner/gem_publisher.rb

@@ -1,10 +1,13 @@
-require "fileutils"
 require_relative "commands"
+require_relative "clean_tree"
+require_relative "git"
+require_relative "../../cli/release_gem"
+require "hecks/hecks/adapters/codebase/gem_registry"
 
 module Hecks
   module Release
     class Runner
-      # The gem step: hands the push to `bin/release_gem`, which builds and pushes
+      # The gem step: hands the push to `Hecks::CLI::ReleaseGem`, which builds and pushes
       # it with the key 1Password holds; a dry run only builds it, then deletes it.
       class GemPublisher
         # @param root [String] the repository root
@@ -14,6 +17,7 @@ module Hecks
           @root = root
           @commands = commands
           @console = console
+          @registry = Hecks::Adapters::Codebase::GemRegistry.new(root: root, commands: commands)
         end
 
         # Pushes the gem, or with `dry_run` only builds it.
@@ -22,20 +26,23 @@ module Hecks
         # @param dry_run [Boolean] build and delete the gem, pushing nothing
         # @return [void]
         # @raise [CommandFailed] if the build or the push fails
+        # @raise [Refusal] if a packaged path holds a modified, untracked or ignored file
         def publish!(version, dry_run:)
           return build_only(version) if dry_run
 
-          @console.say("Publishing hecks #{version} to rubygems.org via bin/release_gem...")
-          @commands.run!(File.join(@root, "bin/release_gem"), chdir: @root)
+          CleanTree.new(git: Git.new(root: @root, commands: @commands)).check!
+
+          @console.say("Publishing hecks #{version} to rubygems.org...")
+          status = Hecks::CLI::ReleaseGem.call(root: @root, commands: @commands, out: @console.out,
+                                               err: @console.err, version: version)
+          raise CommandFailed, "the gem push was refused" unless status.zero?
         end
 
         private
 
         def build_only(version)
           @console.say("Dry run: building hecks-#{version}.gem (nothing is pushed)...")
-          @commands.run!("gem", "build", "hecks.gemspec", chdir: @root)
-        ensure
-          FileUtils.rm_f(File.join(@root, "hecks-#{version}.gem"))
+          @registry.build_only!(version)
         end
       end
     end

data/lib/hecks/release/runner/npm_publisher.rb

@@ -1,5 +1,5 @@
-require "tempfile"
 require_relative "commands"
+require "hecks/hecks/adapters/codebase/npm_registry"
 
 module Hecks
   module Release
@@ -7,16 +7,13 @@ module Hecks
       # The npm step: publishes `@hecks/client` from `packages/hecks-client`
       # with the token 1Password holds.
       class NpmPublisher
-        PACKAGE_DIR = "packages/hecks-client".freeze
-        ENV_FILE = "release/npm_publish.env".freeze
         APPROVAL_NOTICE = "npm will print an approval link; open it and approve with your security key or passkey. " \
                           "This step waits for you.".freeze
-        USERCONFIG_LINE = "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}".freeze
 
         def initialize(root:, commands:, console:)
           @root = root
-          @commands = commands
           @console = console
+          @registry = Hecks::Adapters::Codebase::NpmRegistry.new(root: root, commands: commands)
         end
 
         # Publishes the package, or with `dry_run` only packs it, which needs no
@@ -25,49 +22,22 @@ module Hecks
           install_dependencies
           if dry_run
             @console.say("Dry run: npm publish --dry-run for @hecks/client #{version} (nothing is published)...")
-            @commands.run!("npm", "publish", "--dry-run", "--access", "public", chdir: package_dir)
+            @registry.dry_publish!
           else
             @console.say("Publishing @hecks/client #{version} to npm (1Password will prompt for Touch ID)...")
             @console.say(APPROVAL_NOTICE)
-            publish_with_token
+            @registry.publish!
           end
         end
 
         private
 
-        def package_dir
-          File.join(@root, PACKAGE_DIR)
-        end
-
         # npm's `prepack` hook builds `dist/`; there is no separate build step here.
         def install_dependencies
-          return if Dir.exist?(File.join(package_dir, "node_modules"))
+          return if @registry.installed?
 
           @console.say("Installing the client's dependencies (npm ci)...")
-          @commands.run!("npm", "ci", chdir: package_dir)
-        end
-
-        # The token bypasses 2FA (the account's second factor is a passkey); this
-        # fallback publish runs with `--auth-type=web` and doesn't capture output,
-        # so an approval prompt reaches the terminal.
-        def publish_with_token
-          with_userconfig do |userconfig|
-            @commands.run!(
-              "op", "run", "--env-file=#{File.join(@root, ENV_FILE)}", "--",
-              "npm", "publish", "--access", "public", "--auth-type=web", "--userconfig", userconfig,
-              chdir: package_dir
-            )
-          end
-        end
-
-        def with_userconfig
-          file = Tempfile.new(["hecks-npmrc", ".npmrc"])
-          file.chmod(0o600)
-          file.write("#{USERCONFIG_LINE}\n")
-          file.flush
-          yield file.path
-        ensure
-          file&.close!
+          @registry.install!
         end
       end
     end

data/lib/hecks/release/runner/preflight.rb

@@ -1,6 +1,7 @@
 require "json"
 require_relative "commands"
 require_relative "git"
+require_relative "clean_tree"
 
 module Hecks
   module Release
@@ -20,6 +21,7 @@ module Hecks
         }.freeze
         VERSION_LINE = /^\s*VERSION\s*=\s*"(?<version>[^"]+)"/
         CLIENT_PACKAGE = "packages/hecks-client/package.json".freeze
+        HOST_RELEASE_FILE = "rust/host/HECKS_RELEASE".freeze
 
         def initialize(root:, commands:, git:, tools:)
           @root = root
@@ -28,6 +30,14 @@ module Hecks
           @tools = tools
         end
 
+        # Refuses when a tool the release runs is not installed.
+        #
+        # @return [void]
+        # @raise [Refusal] naming the tool and how to install it
+        def check_tools!
+          check_tools
+        end
+
         # Runs every check; the first refusal stops it.
         def check!
           check_tools
@@ -36,6 +46,7 @@ module Hecks
           check_clean
           version = declared_version
           check_client_version(version)
+          check_host_release(version)
           check_changelog(version)
           Facts.new(version: version, sha: git("rev-parse", "HEAD").strip)
         end
@@ -70,9 +81,11 @@ module Hecks
         end
 
         def check_clean
-          return if git("status", "--porcelain").strip.empty?
+          unless git("status", "--porcelain").strip.empty?
+            raise Refusal, "the working tree has uncommitted changes; commit or discard them before releasing"
+          end
 
-          raise Refusal, "the working tree has uncommitted changes; commit or discard them before releasing"
+          CleanTree.new(git: @git).check!
         end
 
         def declared_version
@@ -89,6 +102,17 @@ module Hecks
           raise Refusal, "packages/hecks-client is at #{client} but Hecks::VERSION is #{version}; bump the package first."
         end
 
+        # The Rust host reports the Hecks release it was built for from this file, and the
+        # committed-approval gate compares rehearsals against it.
+        def check_host_release(version)
+          path = File.join(@root, HOST_RELEASE_FILE)
+          host = File.exist?(path) ? File.read(path).strip : nil
+          return if host == version
+
+          raise Refusal, "#{HOST_RELEASE_FILE} says #{host.inspect} but Hecks::VERSION is #{version}; " \
+                         "write #{version} into it in the release PR."
+        end
+
         def check_changelog(version)
           return if File.read(File.join(@root, "CHANGELOG.md")).match?(/^## \[#{Regexp.escape(version)}\]/)
 

data/lib/hecks/release/runner/published.rb

@@ -1,5 +1,6 @@
-require "json"
 require_relative "commands"
+require "hecks/hecks/adapters/codebase/gem_registry"
+require "hecks/hecks/adapters/codebase/npm_registry"
 
 module Hecks
   module Release
@@ -7,16 +8,14 @@ module Hecks
       # Asks the registries whether a version is already out, so a re-run of the
       # release skips what an earlier run finished.
       #
-      # Neither question needs credentials.
+      # Neither question needs credentials. The registries themselves are the GemRegistry and
+      # NpmRegistry adapters.
       class Published
-        GEM_VERSIONS_URL = "https://rubygems.org/api/v1/versions/hecks.json".freeze
-        NPM_PACKAGE = "@hecks/client".freeze
-
         # @param root [String] the repository root
         # @param commands [#capture] runs curl and npm
         def initialize(root:, commands:)
-          @root = root
-          @commands = commands
+          @gems = Hecks::Adapters::Codebase::GemRegistry.new(root: root, commands: commands)
+          @npm = Hecks::Adapters::Codebase::NpmRegistry.new(root: root, commands: commands)
         end
 
         # Says whether RubyGems lists the hecks gem at a version.
@@ -24,31 +23,14 @@ module Hecks
         # @param version [String] the version to look for
         # @return [Boolean] true when it is published
         # @raise [Refusal] if RubyGems cannot be reached or answers with something unreadable
-        def gem?(version)
-          result = @commands.capture("curl", "-fsS", GEM_VERSIONS_URL, chdir: @root)
-          unless result.success?
-            raise Refusal, "could not list published hecks versions (#{result.stderr.strip}); " \
-                           "check the network and re-run"
-          end
-
-          JSON.parse(result.stdout).any? { |entry| entry["number"] == version }
-        rescue JSON::ParserError
-          raise Refusal, "RubyGems answered with something other than a version list; re-run in a minute"
-        end
+        def gem?(version) = @gems.published?(version)
 
         # Says whether npm lists @hecks/client at a version.
         #
         # @param version [String] the version to look for
         # @return [Boolean] true when it is published
         # @raise [Refusal] if npm fails for any reason other than the version not existing
-        def npm?(version)
-          result = @commands.capture("npm", "view", "#{NPM_PACKAGE}@#{version}", "version", chdir: @root)
-          return result.stdout.strip == version if result.success?
-          return false if result.stderr.include?("E404")
-
-          raise Refusal, "could not check npm for #{NPM_PACKAGE}@#{version} (#{result.stderr.strip.lines.first}); " \
-                         "check the network and re-run"
-        end
+        def npm?(version) = @npm.published?(version)
       end
     end
   end

data/lib/hecks/release/runner/tagger.rb

@@ -11,24 +11,50 @@ module Hecks
           @git = git
           @console = console
           @dry_run = dry_run
+          @changed = false
+        end
+
+        # @return [Boolean] whether this run created or pushed the tag, for real
+        def changed?
+          @changed
         end
 
         # Brings the tag to the state described above, saying what it did; returns
         # false only when the person declined the confirmation.
-        def ensure!(facts)
+        #
+        # @param facts [#version, #sha] the release
+        # @param note [String, nil] what pushing the tag sets off, worded into the question
+        def ensure!(facts, note: nil)
           tag = "v#{facts.version}"
           local = local_commit(tag)
           remote = remote_commit(tag)
           refuse_elsewhere(tag, facts.sha, local: local, remote: remote)
           return true.tap { already_there(tag) } if remote
           return true.tap { preview(tag, facts.sha, local) } if @dry_run
-          return false unless @console.confirm?(question(tag, facts.sha, local))
+          return false unless @console.confirm?(question(tag, facts.sha, local, note))
 
           create(tag, facts.sha) unless local
           push(tag)
+          @changed = true
           true
         end
 
+        # @param tag [String] the tag, such as `v3.0.0`
+        # @return [String, nil] the commit the tag points at in this checkout, or nil when absent
+        def local_commit(tag)
+          result = @git.capture("rev-parse", "-q", "--verify", "refs/tags/#{tag}^{commit}")
+          result.success? ? result.stdout.strip : nil
+        end
+
+        # @param tag [String] the tag, such as `v3.0.0`
+        # @return [String, nil] the commit the tag points at on origin, or nil when it is not there
+        # @raise [Refusal] when the remote's tags cannot be listed
+        def remote_commit(tag)
+          listing = @git.read("ls-remote", "--tags", "origin", "refs/tags/#{tag}", "refs/tags/#{tag}^{}")
+          shas = listing.lines.to_h { |line| line.split.then { |sha, ref| [ref, sha] } }
+          shas.fetch("refs/tags/#{tag}^{}") { shas["refs/tags/#{tag}"] }
+        end
+
         private
 
         def already_there(tag)
@@ -40,9 +66,9 @@ module Hecks
           @console.say("Would push #{tag} to origin.")
         end
 
-        def question(tag, sha, local)
+        def question(tag, sha, local, note)
           verb = local ? "Push" : "Create and push"
-          "#{verb} annotated tag #{tag} at #{sha[0, 7]} to origin?"
+          "#{verb} annotated tag #{tag} at #{sha[0, 7]} to origin#{" (#{note})" if note}?"
         end
 
         def create(tag, sha)
@@ -63,17 +89,6 @@ module Hecks
                            "and the missing package must be published from a checkout of #{tag}"
           end
         end
-
-        def local_commit(tag)
-          result = @git.capture("rev-parse", "-q", "--verify", "refs/tags/#{tag}^{commit}")
-          result.success? ? result.stdout.strip : nil
-        end
-
-        def remote_commit(tag)
-          listing = @git.read("ls-remote", "--tags", "origin", "refs/tags/#{tag}", "refs/tags/#{tag}^{}")
-          shas = listing.lines.to_h { |line| line.split.then { |sha, ref| [ref, sha] } }
-          shas.fetch("refs/tags/#{tag}^{}") { shas["refs/tags/#{tag}"] }
-        end
       end
     end
   end

data/lib/hecks/release/runner.rb

@@ -94,9 +94,16 @@ module Hecks
       # @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) })
+                     pause: ->(seconds) { sleep(seconds) }, now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
+                     facts: nil)
         @root = root
+        @facts = facts
+        @steps = []
+        @verified = false
         @options = options
         @commands = commands
         @console = Console.new(input: input, out: out, err: err, assume_yes: options.yes?)
@@ -105,16 +112,28 @@ module Hecks
         @ci = CiPublisher.new(root: root, published: @published, console: @console, pause: pause, now: now)
       end
 
+      # @return [Array<Symbol>] the steps this run carried out for real: `:tagged`, `:gem`, `:npm`
+      attr_reader :steps
+
+      # @return [Boolean] whether, after a real run, every registry in scope lists the version
+      attr_reader :verified
+
       # Runs the release.
       #
       # @return [Integer] 0 when the release finished or had nothing to do, 1 when a check refused,
       #   a step failed, CI's publish did not arrive in time or a confirmation was declined
       def call
-        facts = Preflight.new(root: @root, commands: @commands, git: @git, tools: tools).check!
+        facts = preflight
         pending = pending_steps(facts.version)
         require_workflow(pending)
-        return declined unless Tagger.new(git: @git, console: @console, dry_run: @options.dry_run).ensure!(facts)
+        # Nothing is tagged or pushed until the person has agreed to the publish: the tag push
+        # 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)
       rescue Refusal, CommandFailed => e
         @console.warn(e.message)
@@ -123,6 +142,14 @@ module Hecks
 
       private
 
+      def preflight
+        check = Preflight.new(root: @root, commands: @commands, git: @git, tools: tools)
+        return check.check! unless @facts
+
+        check.check_tools!
+        @facts
+      end
+
       def tools
         list = %w[git curl]
         list << "gem" if @options.gem?
@@ -143,6 +170,11 @@ module Hecks
         published
       end
 
+      # The steps this run's flags put in scope, whether or not a registry already lists them.
+      def in_scope
+        [(:gem if @options.gem?), (:npm if @options.npm?)].compact
+      end
+
       def ci_publishes?(pending)
         pending.include?(:npm) && !@options.npm_local?
       end
@@ -157,13 +189,19 @@ module Hecks
       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
-        return declined unless @options.dry_run || publish_confirmed?(facts.version, pending)
-
         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)
@@ -179,29 +217,42 @@ module Hecks
         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: bin/release --npm-only --npm-local (published steps are not repeated)")
+          @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

data/lib/hecks/router/namespace_installer.rb

@@ -1,5 +1,5 @@
 require_relative "../fqn"
-require_relative "../facade/handle"
+require_relative "../doors/handle"
 
 module Hecks
   class Router
@@ -100,12 +100,12 @@ module Hecks
 
         target.define_singleton_method(:find) do |id|
           found = dispatcher.registry.repository(domain, ir).find(id)
-          found && Facade::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: found)
+          found && Doors::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: found)
         end
 
         target.define_singleton_method(:all) do
           dispatcher.registry.repository(domain, ir).all.map do |instance|
-            Facade::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: instance)
+            Doors::Handle.new(dispatcher: dispatcher, domain: domain, aggregate: ir, instance: instance)
           end
         end
       end

data/lib/hecks/runtime/adapter_lookup.rb

@@ -0,0 +1,124 @@
+require_relative "errors"
+
+module Hecks
+  module Runtime
+    # Finds the one adapter this boot loaded for a port name.
+    #
+    # Shared by the port-operation interpreter (an aggregate asking out) and the query interpreter
+    # (a query answered by a port), so both refuse the same way when nothing, or too much,
+    # implements the port.
+    module AdapterLookup
+      @stand_in = nil
+
+      module_function
+
+      # Modules whose instance methods every object inherits; a method they own answers no query.
+      INHERITED_OWNERS = [Object, Kernel, BasicObject].freeze
+
+      # Answers every port with a stand-in instead of its adapter while the block runs, for a
+      # caller that must not reach what the adapters reach (the fuzzer replays a domain whose
+      # adapters run shells and write files). Boot still checks the real adapters' classes; only
+      # what `call` hands out changes.
+      #
+      # @param stand_in [#call] answers `(port_name, asked)` with the object to ask instead
+      # @yield the work to run with the stand-in in place
+      # @return [Object] what the block answers
+      def standing_in(stand_in)
+        previous = @stand_in
+        @stand_in = stand_in
+        yield
+      ensure
+        @stand_in = previous
+      end
+
+      # @param registry [Runtime::Registry] the booted registry whose adapters are searched
+      # @param port_name [String] the port's name as an adapter declares it
+      # @param asked [String] what is being asked, worded into a refusal
+      # @return [Object] a new instance of the port's only adapter, or the stand-in for it
+      # @raise [Runtime::WiringError] if no adapter, or more than one, implements the port
+      def call(registry, port_name, asked:)
+        adapter_class(registry, port_name, asked: asked)
+        return @stand_in.call(port_name, asked) if @stand_in
+
+        adapter_class(registry, port_name, asked: asked).new
+      end
+
+      # Finds the class of the one adapter this boot loaded for a port name, without building it,
+      # so boot can check what the adapter answers before anything asks it.
+      #
+      # @param registry [Runtime::Registry] the booted registry whose adapters are searched
+      # @param port_name [String] the port's name as an adapter declares it
+      # @param asked [String] what is being asked, worded into a refusal
+      # @return [Class] the port's only adapter
+      # @raise [Runtime::WiringError] if no adapter, or more than one, implements the port
+      def adapter_class(registry, port_name, asked:)
+        implementations = registry.adapters.values.select { |adapter| adapter.port == port_name }
+
+        case implementations.size
+        when 1 then Adapters.const_get(implementations.first.name)
+        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"
+        end
+      end
+
+      # Checks that an adapter class can be built with a bare `.new` and answers a query: it
+      # defines the method itself (not inherited from Object or Kernel, so a query named `hash` or
+      # `display` is not answered by them) and takes exactly the query's arguments as keywords.
+      #
+      # @param klass [Class] the adapter class {adapter_class} found
+      # @param port_name [String] the port's name, worded into a refusal
+      # @param method [String] the snake-cased query name the adapter is asked by
+      # @param query [Bluebook::Query] the declared query whose arguments the method must take
+      # @param asked [String] what is being asked, worded into a refusal
+      # @return [void]
+      # @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:)
+        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
+
+        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
+
+        check_keywords!(klass, method, query, 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)
+        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)
+        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(', ')})"
+      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
+      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?
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -30,6 +30,10 @@ module Hecks
                       @rules.resolve_source(mutation.source,
                                             args)
                     end
+            # A plain `sets` of a list takes the whole list; only `append:` and `remove:` take
+            # one element.
+            list_attribute = aggregate.attribute(mutation.target)
+            Value.refuse_scalar_list(aggregate, list_attribute, value) if list_attribute && !mutation.source.is_a?(StateRef)
             instance[mutation.target] = Value.for(aggregate, mutation.target, value)
           when :append
             instance[mutation.target] = appended(pre, aggregate, mutation, args)