hecks 2.8.0 → 3.0.0

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

@@ -1,22 +1,15 @@
 require "json"
 require_relative "commands"
 require_relative "git"
+require_relative "clean_tree"
 
 module Hecks
   module Release
     class Runner
-      # The checks that run before a release does anything: the tools are
-      # installed, the checkout is a clean, current `main`, the gem and the
-      # JavaScript client agree on a version, and the changelog names it.
-      #
-      # Every refusal says what to do about it.
+      # The checks that run before a release does anything: tools installed, a
+      # clean current `main`, matching versions, and a changelog entry.
       class Preflight
-        # What the checks learned about the release.
-        #
-        # @!attribute [r] version
-        #   @return [String] the version `lib/hecks/version.rb` declares
-        # @!attribute [r] sha
-        #   @return [String] the commit `HEAD` points at, which is also `origin/main`
+        # What the checks learned; `sha` is also `origin/main`, enforced by check_current.
         Facts = Struct.new(:version, :sha, keyword_init: true)
 
         INSTALL_HINTS = {
@@ -28,11 +21,8 @@ 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
 
-        # @param root [String] the repository root
-        # @param commands [#capture] runs the tool probes
-        # @param git [Git] the repository the release is cut from
-        # @param tools [Array<String>] the executables the release needs on PATH
         def initialize(root:, commands:, git:, tools:)
           @root = root
           @commands = commands
@@ -40,10 +30,15 @@ module Hecks
           @tools = tools
         end
 
-        # Runs every check.
+        # Refuses when a tool the release runs is not installed.
         #
-        # @return [Facts] the version and commit the release is cut from
-        # @raise [Refusal] on the first check that fails, naming the fix
+        # @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
           check_branch
@@ -51,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
@@ -85,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
@@ -104,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

@@ -7,35 +7,54 @@ module Hecks
       # Makes sure the release tag `vX.Y.Z` is an annotated tag on the release
       # commit and is on origin, creating and pushing it only when it is missing.
       class Tagger
-        # @param git [Git] the repository the release is cut from
-        # @param console [Console] asks before the tag is created or pushed
-        # @param dry_run [Boolean] report what would happen and change nothing
         def initialize(git:, console:, dry_run:)
           @git = git
           @console = console
           @dry_run = dry_run
+          @changed = false
         end
 
-        # Brings the tag to the state described above, saying what it did.
+        # @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.
         #
-        # @param facts [Preflight::Facts] the version and commit being released
-        # @return [Boolean] false when the person declined the question, true otherwise
-        # @raise [Refusal] if the tag already points at another commit, locally or on origin
-        # @raise [CommandFailed] if creating or pushing the tag fails
-        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)
@@ -47,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)
@@ -70,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

@@ -11,39 +11,10 @@ require_relative "runner/ci_publisher"
 module Hecks
   module Release
     # Performs the release once the release PR has merged: tags the merge
-    # commit, publishes the gem to rubygems.org and gets the JavaScript client
-    # published to npm.
+    # commit, publishes the gem, and gets the JS client published to npm.
     #
-    # ## Why it exists
-    #
-    # A release is four steps that have to happen in one order, and only
-    # the contributing guide remembered it. This runs them in that order, refuses to
-    # start from a checkout that is not the merged `main`, and can be run again:
-    # 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.
-    #
-    # ## Steps
-    #
-    # 1. Preflight: tools installed, on a clean `main` equal to `origin/main`,
-    #    the gem and the client at one version, the changelog naming it.
-    # 2. Published state: which of the gem and the package are already out.
-    # 3. Tag: an annotated `vX.Y.Z` on the release commit, pushed to origin.
-    # 4. Gem: `bin/release_gem`, unchanged.
-    # 5. npm, one of two ways:
-    #    - by default CI publishes: the tag triggers `publish-client.yml`, which
-    #      uses npm trusted publishing, and this waits for the version to appear
-    #      (`--no-wait` skips the wait);
-    #    - with `--npm-local` this publishes from the machine, with a
-    #      bypass-two-factor token 1Password holds: the way to make the first
-    #      publish, before trusted publishing can be configured, and the fallback
-    #      when CI is down.
-    #
-    # ## Injectable commands and time
-    #
-    # Every process is started through `commands`, any object answering
-    # `capture(*argv, env:, chdir:)` and `run!(*argv, env:, chdir:)` like
-    # {Commands}, so a spec drives the whole release with a recorder. The wait for
-    # CI takes its clock and its pause as callables for the same reason.
+    # 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
@@ -123,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?)
@@ -134,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)
@@ -152,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?
@@ -172,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
@@ -186,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)
@@ -208,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/rendering.rb

@@ -1,19 +1,9 @@
 require "json"
 
 module Hecks
-  # How a value reads inside a refusal, in one place, because a refusal is an
-  # answer and its wording is contract — pinned byte-for-byte by the corpus.
+  # How a value reads inside a refusal; the wording is contract, pinned by the corpus.
   #
-  # `inspect` and JSON agree on scalars and disagree on everything composite :
-  # a hash is `{"cents"=>100}` against `{"cents":100}`, an array is `["a", "b"]`
-  # against `["a","b"]`. Each such spelling is invisible until a composite
-  # actually reaches a message, which is why both known cases were found by
-  # something deliberately passing the wrong shape rather than by review — the
-  # first by hand in spec/corpus/banking.json, the second by bin/fuzz, at a
-  # different site, after the first was patched where it was found.
-  #
-  # So it lives here rather than in whichever file noticed it, and the house style
-  # is JSON because that is what every other refusal in the corpus already prints.
+  # `inspect` and JSON disagree on composites, so refusals use JSON throughout.
   module Rendering
     module_function
 
@@ -28,20 +18,8 @@ module Hecks
       when nil then "nil"
       when Hash, Array then JSON.generate(value)
       else
-        # A Hecks::Runtime::Value reaching a refusal message (an
-        # arithmetic op's own `amount`/`current`, an Admissibility
-        # `current`, ...) had no case here, falling straight through to
-        # Ruby's own #inspect and leaking a raw object pointer
-        # ("#<Hecks::Runtime::Value:0x...>") into an otherwise
-        # correct domain refusal. Duck-typed on `respond_to?(:to_h)`
-        # rather than naming `Runtime::Value` directly — `Runtime::Value`
-        # itself requires this file (`runtime/value.rb`'s own
-        # `require_relative "../rendering"`), so naming it here would be
-        # circular. A single-field wrapper (the overwhelming common case
-        # — an amount, an id, a lifecycle field) unwraps to its bare
-        # scalar, described recursively; a genuinely multi-field value
-        # renders as its fields' JSON, same as a bare Hash already does
-        # two lines up.
+        # 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)

data/lib/hecks/router/namespace_installer.rb

@@ -1,24 +1,15 @@
 require_relative "../fqn"
-require_relative "../facade/handle"
+require_relative "../doors/handle"
 
 module Hecks
   class Router
-    # Installs optional Ruby syntax over an already-loaded router. FQN
-    # resolution stays in Router; this object only adapts it to constants and
-    # method calls.
+    # 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 the `.options(version:)` method installed on each
-      # namespace module — forwards any command/query verb called on it
-      # to the router, pinned to this specific FQN version rather than
-      # the router's default resolution.
+      # Returned by `.options(version:)`; forwards command/query verbs to the
+      # router, pinned to this FQN version rather than the router's default.
       class OptionsProxy
-        # @param router [Router] router to dispatch resolved calls through
-        # @param realm [String, nil] realm segment of the FQN this proxy pins
-        # @param domain [String] domain segment of the FQN this proxy pins
-        # @param aggregate [String, nil] aggregate segment, or nil for a domain-level query
-        # @param options [Hash{Symbol => Object}] the `.options(...)` call's keywords; only
-        #   `:version` is accepted
-        # @raise [ArgumentError] if `options` has a key other than `:version`
+        # 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?
@@ -52,16 +43,12 @@ module Hecks
         end
       end
 
-      # @param router [Router] router whose current routes get Ruby constants and methods
       def initialize(router)
         @router = router
       end
 
-      # Installs every current-version route as a namespace constant/method,
-      # plus the aggregate `find`/`all`/`count`/`events`/`repository` door and
-      # short `Aggregate.verb` shortcuts.
-      #
-      # @return [self]
+      # Installs every current-version route as a namespace constant/method, plus
+      # the aggregate CRUD door and short `Aggregate.verb` shortcuts.
       def install!
         current_entries.each { |entry| install_namespace_entry(entry) }
         install_shortcuts!
@@ -90,18 +77,8 @@ module Hecks
         end
       end
 
-      # `.find`/`.all`/`.count`/`.events`/`.repository` — the same read/CRUD
-      # surface `Facade::Surface::AggregateDoor` gives a plain `Hecks
-      # .boot`, missing here until now: `install_namespace_entry` above
-      # installs one method per declared verb, so an aggregate with no
-      # commands or queries of its own shape (or simply never asked for
-      # a `find`-shaped query) had no way to look up one record by id
-      # through the router surface at all — real gap, hit live building
-      # a `List` aggregate meant to be read this way. Grouped by
-      # (realm, domain, aggregate) rather than installed per-verb,
-      # because unlike a command or query this is the same five methods
-      # regardless of which verb happened to trigger this aggregate's
-      # own namespace module into existing.
+      # `.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!
         current_entries.reject { |entry| entry.fqn.aggregate.nil? }
                        .group_by { |entry| [entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate] }
@@ -123,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
@@ -138,10 +115,9 @@ module Hecks
         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 still
-          # get the shortcut — they are not BCs.
+          # 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|

data/lib/hecks/router.rb

@@ -16,8 +16,7 @@ module Hecks
     # @return [Router] the built router
     def self.load(root) = new(Bluebook::ProjectLoader.load(root))
 
-    # Install one project router for ordinary application calls. The explicit
-    # `Router.load` API remains useful for tests and embedded hosts.
+    # Installs one project router as `.default` for ordinary application calls.
     #
     # @param root [String] project root to discover bluebooks under
     # @return [Router] the booted router, also stored as `.default`
@@ -75,14 +74,12 @@ module Hecks
     # Dispatches a command to its resolved aggregate.
     #
     # @param address [String] a fully-qualified command address, realm included
-    # @param args [Hash] command facts, plus the dispatcher's optional `:to`, `:with`,
-    #   and `:saga_correlation` keys
+    # @param args [Hash] command facts, plus optional `:to`, `:with`, `:saga_correlation`
     # @return [Runtime::Dispatcher::Result] the dispatch result
     # @raise [UnknownAddress] if `address` has no realm, or names no known route
     # @raise [WrongVerbKind] if `address` names a query
     # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
-    # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the domain refuses
-    #   the call
+    # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class when the domain refuses
     # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
     # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def dispatch(address, **args)
@@ -97,13 +94,12 @@ module Hecks
     # @param address [String] a fully-qualified query address, realm included
     # @param args [Hash{Symbol => Object}] the query's declared arguments
     # @return [Array<Hash>] one row Hash per match; see `Runtime::Dispatcher#query`
-    #   for the exact shape per address kind
     # @raise [UnknownAddress] if `address` has no realm, or names no known route
     # @raise [WrongVerbKind] if `address` names a command
     # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
     # @raise [Runtime::NotFound] if a read model's root reference names no record
     # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
-    # @raise [KeyError] if a rooted read model is asked without its reference argument
+    # @raise [KeyError] if a rooted read model lacks its reference argument
     # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def query(address, **args)
       entry = resolve(address)