hecks 3.5.0 → 3.6.0

data/lib/hecks/embryonaut_bluebook/registry.rb

@@ -3,6 +3,8 @@ require "tmpdir"
 require "fileutils"
 require_relative "../vendoring"
 require_relative "lock"
+require_relative "registry/changelog"
+require_relative "registry/versions"
 
 module Hecks
   module EmbryonautBluebook
@@ -14,6 +16,9 @@ module Hecks
     # a changelog entry; `release` is the sequence of refusals before a tag is made. A package's
     # files are compared through `Lock.digest_of`, the digest a consuming project locks.
     class Registry
+      include Changelog
+      include Versions
+
       # A version a package may carry, `X.Y.Z`.
       VERSION = /\A\d+\.\d+\.\d+\z/
 
@@ -86,12 +91,22 @@ module Hecks
       # @return [Tagged] the tag made and the commit it stands on
       # @raise [Vendoring::Error] with the first refusal
       def release(package)
+        version = releasable_version(package)
+        tag = "#{package}-v#{version}"
+        refuse_release!(package, version, tag)
+        create_tag(package, version, tag)
+      end
+
+      private
+
+      def releasable_version(package)
         fault!("#{package.inspect} is not a package name") unless package.to_s.match?(NAME)
         version = manifest_version(package) or fault!("no #{package}/bluebook.yml")
         fault!("#{package}/bluebook.yml: version '#{version}' is not X.Y.Z") unless version.match?(VERSION)
+        version
+      end
 
-        tag = "#{package}-v#{version}"
-        refuse_release!(package, version, tag)
+      def create_tag(package, version, tag)
         notes = changelog_section(package, version)
         _, _, status = git("tag", "-a", tag, "-m", "#{package} #{version}", "-m", notes)
         raise Vendoring::Error, "git could not tag #{tag}" unless status.success?
@@ -99,8 +114,6 @@ module Hecks
         Tagged.new(tag: tag, commit: git("rev-parse", "--short", "HEAD").first.strip)
       end
 
-      private
-
       def packages
         Dir.glob(File.join(@root, "*", "bluebook.yml")).map { |file| File.basename(File.dirname(file)) }.sort
       end
@@ -111,8 +124,7 @@ module Hecks
           report.fault "#{package}: version '#{version}' is not X.Y.Z"
           return
         end
-        name = File.read(File.join(@root, package, "bluebook.yml"))[/^name: *(.*)$/, 1]
-        report.fault "#{package}: bluebook.yml name does not match the directory" unless name == package
+        check_name(package, report)
         tags(package).each { |tag| check_tag(package, tag, report) }
         latest = latest_version(package)
         return report.note("#{package}: no release tag yet (#{version} unreleased)") unless latest
@@ -120,6 +132,11 @@ module Hecks
         check_changes(package, version, latest, report)
       end
 
+      def check_name(package, report)
+        name = File.read(File.join(@root, package, "bluebook.yml"))[/^name: *(.*)$/, 1]
+        report.fault "#{package}: bluebook.yml name does not match the directory" unless name == package
+      end
+
       def check_tag(package, tag, report)
         tagged = @source.read(tag, "#{package}/bluebook.yml").to_s[/^version: *(.*)$/, 1].to_s
         return if tagged == tag.delete_prefix("#{package}-v")
@@ -146,6 +163,10 @@ module Hecks
         fault!("#{version} is not newer than the latest release #{latest}") if latest && newest(latest, version) != version
         fault!("#{package}/CHANGELOG.md has no '## #{version}' entry") unless changelog_entry?(package, version)
         fault!("#{package} has uncommitted changes; commit them first") unless clean?(package)
+        refuse_unchanged!(package, latest)
+      end
+
+      def refuse_unchanged!(package, latest)
         return unless latest && released_digest(package, latest) == current_digest(package)
 
         fault!("the bluebook files are identical to #{package}-v#{latest}; nothing to release")
@@ -155,37 +176,6 @@ module Hecks
 
       def clean?(package) = git("status", "--porcelain", "--", package).first.strip.empty?
 
-      def manifest_version(package)
-        file = File.join(@root, package, "bluebook.yml")
-        File.file?(file) ? File.read(file)[/^version: *(.*)$/, 1] : nil
-      end
-
-      def tags(package) = @source.tags("#{package}-v*")
-
-      def latest_version(package)
-        tags(package).map { |tag| tag.delete_prefix("#{package}-v") }.max_by { |version| order(version) }
-      end
-
-      # The greater of two versions, compared as `sort -V` does: runs of digits as numbers.
-      def newest(left, right) = [left, right].max_by { |version| order(version) }
-
-      def order(version) = version.scan(/\d+|\D+/).map { |part| part.match?(/\A\d/) ? [0, part.to_i, ""] : [1, 0, part] }
-
-      def changelog_entry?(package, version)
-        file = File.join(@root, package, "CHANGELOG.md")
-        File.file?(file) && File.read(file).match?(/^## #{Regexp.escape(version)}( |$)/)
-      end
-
-      # The lines under a version's heading, up to the next heading, without trailing blank lines.
-      def changelog_section(package, version)
-        on = false
-        lines = File.readlines(File.join(@root, package, "CHANGELOG.md"), chomp: true).select do |line|
-          on = line.match?(/^## #{Regexp.escape(version)}( |$)/) if line.start_with?("## ")
-          on && !line.start_with?("## ")
-        end
-        lines.join("\n").sub(/\n+\z/, "")
-      end
-
       def current_digest(package)
         dir = File.join(@root, package, "bluebook")
         File.directory?(dir) ? Lock.digest_of(dir) : nil

data/lib/hecks/embryonaut_bluebook/vendor/acceptance.rb

@@ -0,0 +1,37 @@
+module Hecks
+  module EmbryonautBluebook
+    class Vendor
+      # The refusals a release pin passes through: a downgrade, and a storage-shape change that is
+      # only a patch bump. Included in `Vendor`.
+      module Acceptance
+        private
+
+        def refuse_unless_acceptable!(version, previous, shape)
+          return unless previous.version
+
+          refuse_downgrade!(version, previous.version)
+          return if previous.shape.nil? || previous.shape == shape
+          return if minor_or_more?(previous.version, version)
+
+          raise Vendoring::Error,
+                "#{@name} #{previous.version} -> #{version} changes the storage shape but is only a patch bump " \
+                "(before: #{previous.shape.join(" ")}; after: #{shape.join(" ")}). Raise the package's version " \
+                "by at least a minor in the source repository and release again. Nothing was changed."
+        end
+
+        def refuse_downgrade!(version, previous_version)
+          return if @allow_downgrade || Gem::Version.new(version) >= Gem::Version.new(previous_version)
+
+          raise Vendoring::Error, "#{@name} #{previous_version} is vendored; #{version} is older. " \
+                                  "Pass allow_downgrade (ALLOW_DOWNGRADE=1 on the command line) to do it anyway."
+        end
+
+        def minor_or_more?(old, new)
+          old_major, old_minor = old.split(".").map(&:to_i)
+          new_major, new_minor = new.split(".").map(&:to_i)
+          new_major > old_major || (new_major == old_major && new_minor > old_minor)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/vendor.rb

@@ -2,12 +2,15 @@ require "fileutils"
 require_relative "../vendoring"
 require_relative "lock"
 require_relative "shape"
+require_relative "vendor/acceptance"
 
 module Hecks
   module EmbryonautBluebook
     # Pins a package's `bluebook/*.bluebook` files from a source repo commit; a
     # release pin also refuses a downgrade or an era-breaking storage-shape change.
     class Vendor
+      include Acceptance
+
       # A release version, `X.Y.Z`.
       VERSION = /\A\d+\.\d+\.\d+\z/
 
@@ -23,6 +26,9 @@ module Hecks
         def shape_changed? = !previous_shape.nil? && previous_shape != shape
       end
 
+      # The version and storage shape already vendored; nil for each when there is no earlier copy.
+      Previous = Struct.new(:version, :shape)
+
       # `ref` accepts `X.Y.Z`, a release tag name, any commit-ish, or nil for
       # the newest release.
       def initialize(name, from:, root:, ref: nil, allow_downgrade: false)
@@ -38,23 +44,29 @@ module Hecks
       # Pins the package and reports what changed.
       def call
         tag, version = release
-        previous_version, previous_shape = existing
+        previous = Previous.new(*existing)
+        pin, shape = pin_files(tag, version, previous)
+        build_result(pin, tag, version, shape, previous)
+      end
+
+      private
+
+      def package_dir = File.join(@root, "vendor", "embryonaut_bluebooks", @name)
+
+      # @return [Array(Vendoring::Pin, Array<String>)] what was pinned, and the storage shape staged
+      def pin_files(tag, version, previous)
         shape = nil
         pin = Vendoring.pin(from: @source.path, ref: tag || @ref, subtree: "#{@name}/bluebook",
                             into: package_dir, glob: "*.bluebook") do |staged, commit|
           shape = Shape.labels(staged)
           next nil unless tag
 
-          refuse_unless_acceptable!(version, previous_version, previous_shape, shape)
+          refuse_unless_acceptable!(version, previous, shape)
           { "bluebook.lock" => lock(version, tag, commit, staged, shape).to_s }
         end
-        build_result(pin, tag, version, shape, previous_version, previous_shape)
+        [pin, shape]
       end
 
-      private
-
-      def package_dir = File.join(@root, "vendor", "embryonaut_bluebooks", @name)
-
       # Resolves what `ref` asks for into a release tag and its version, or nil
       # for a bare commit.
       def release
@@ -89,7 +101,7 @@ module Hecks
 
         raise Vendoring::Error, "no release #{tag} in #{@source.path} (releases: #{release_tags.sort_by do |v|
           Gem::Version.new(v)
-        end.join(' ')})"
+        end.join(" ")})"
       end
 
       def release_tags
@@ -108,41 +120,15 @@ module Hecks
         [version, nil]
       end
 
-      def refuse_unless_acceptable!(version, previous_version, previous_shape, shape)
-        return unless previous_version
-
-        refuse_downgrade!(version, previous_version)
-        return if previous_shape.nil? || previous_shape == shape
-        return if minor_or_more?(previous_version, version)
-
-        raise Vendoring::Error,
-              "#{@name} #{previous_version} -> #{version} changes the storage shape but is only a patch bump " \
-              "(before: #{previous_shape.join(' ')}; after: #{shape.join(' ')}). Raise the package's version " \
-              "by at least a minor in the source repository and release again. Nothing was changed."
-      end
-
-      def refuse_downgrade!(version, previous_version)
-        return if @allow_downgrade || Gem::Version.new(version) >= Gem::Version.new(previous_version)
-
-        raise Vendoring::Error, "#{@name} #{previous_version} is vendored; #{version} is older. " \
-                                "Pass allow_downgrade (ALLOW_DOWNGRADE=1 on the command line) to do it anyway."
-      end
-
-      def minor_or_more?(old, new)
-        old_major, old_minor = old.split(".").map(&:to_i)
-        new_major, new_minor = new.split(".").map(&:to_i)
-        new_major > old_major || (new_major == old_major && new_minor > old_minor)
-      end
-
       def lock(version, tag, commit, staged, shape)
         Lock.new(package: @name, version: version, tag: tag, commit: commit,
                  digest: Lock.digest_of(staged), shape: shape)
       end
 
-      def build_result(pin, tag, version, shape, previous_version, previous_shape)
+      def build_result(pin, tag, version, shape, previous)
         Result.new(package: @name, commit: pin.commit, version: version, tag: tag,
                    digest: Lock.digest_of(pin.dir), shape: shape, dir: pin.dir,
-                   previous_version: previous_version, previous_shape: previous_shape)
+                   previous_version: previous.version, previous_shape: previous.shape)
       end
     end
   end

data/lib/hecks/embryonaut_bluebook/vendor_cli.rb

@@ -23,16 +23,19 @@ module Hecks
         spec = parse(argv, options)
         return usage(err) unless spec && options[:from]
 
-        name, _, ref = spec.partition("@")
-        result = Vendor.new(name, from: options[:from], root: options[:root], ref: ref.empty? ? nil : ref,
-                                  allow_downgrade: env["ALLOW_DOWNGRADE"] == "1").call
-        report(result, options[:from], out)
+        report(vendor(spec, options, env), options[:from], out)
         0
       rescue Vendoring::Error, OptionParser::ParseError => e
         err.puts(e.message)
         1
       end
 
+      def self.vendor(spec, options, env)
+        name, _, ref = spec.partition("@")
+        Vendor.new(name, from: options[:from], root: options[:root], ref: ref.empty? ? nil : ref,
+                         allow_downgrade: env["ALLOW_DOWNGRADE"] == "1").call
+      end
+
       # nil unless argv held exactly one positional argument.
       def self.parse(argv, options)
         parser = OptionParser.new
@@ -61,13 +64,13 @@ module Hecks
           "Shape: #{now} (no earlier vendored copy to compare against)"
         elsif result.shape_changed?
           "SHAPE CHANGED: the next deploy mints a new era; add its translation edge first.\n  " \
-            "before: #{result.previous_shape.join(' ')}\n  after:  #{now}"
+            "before: #{result.previous_shape.join(" ")}\n  after:  #{now}"
         else
           "Shape unchanged: #{now}. No new era on deploy."
         end
       end
 
-      private_class_method :parse, :usage, :report, :shape_line
+      private_class_method :vendor, :parse, :usage, :report, :shape_line
     end
   end
 end

data/lib/hecks/embryonaut_bluebook.rb

@@ -24,17 +24,7 @@ module Hecks
     # @raise [Runtime::WiringError] if `registry` has no root, or no vendored
     #   package named `name` is checked out
     def self.load!(name, registry: Hecks.current_registry)
-      unless registry&.root
-        raise Runtime::WiringError,
-              "attaches(#{name.inspect}, from: :vendor) needs a registry with a root to vendor from"
-      end
-
-      unless name.to_s.match?(PACKAGE_NAME)
-        raise Runtime::WiringError,
-              "attaches(#{name.inspect}, from: :vendor) is not a package name — it must match " \
-              "[a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
-      end
-
+      check_loadable!(name, registry)
       return if registry.bluebook(Naming.pascal(name.to_s))
 
       dir   = File.join(registry.root, "vendor", "embryonaut_bluebooks", name.to_s, "bluebook")
@@ -51,6 +41,21 @@ module Hecks
       files.each { |file| Kernel.load(file) }
     end
 
+    # @raise [Runtime::WiringError] if `registry` has no root to vendor from, or `name` is not a
+    #   package name
+    def self.check_loadable!(name, registry)
+      unless registry&.root
+        raise Runtime::WiringError,
+              "attaches(#{name.inspect}, from: :vendor) needs a registry with a root to vendor from"
+      end
+      return if name.to_s.match?(PACKAGE_NAME)
+
+      raise Runtime::WiringError,
+            "attaches(#{name.inspect}, from: :vendor) is not a package name — it must match " \
+            "[a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
+    end
+    private_class_method :check_loadable!
+
     # Pins one package of the registry into a project's `vendor/` tree.
     #
     # @param name [String, Symbol] the package's directory name, such as `"payments"`

data/lib/hecks/engine_agreement.rb

@@ -69,23 +69,30 @@ module Hecks
     # @return [Array<String>] a problem for each engine that lost `Comparison.holds?` or grew a case
     def engine_problems(root, declared)
       ENGINE_FILES.flat_map do |label, relative|
-        source = File.read(File.join(root, relative))
-        found = []
-        unless source =~ /Comparison\.holds\?/
-          found << "#{relative} (#{label}) no longer calls Comparison.holds? at all — " \
-                   "has it grown its own comparator dispatch again?"
-        end
-        declared.each do |comparator|
-          escaped = Regexp.escape(comparator)
-          next unless source =~ /when\s+"#{escaped}"/ || source =~ /when\s+:#{escaped}\b/
-
-          found << "#{relative} (#{label}) has its own `when #{comparator.inspect}` — comparator logic " \
-                   "belongs ONLY in #{SHARED_COMPARISON_FILE}, not re-implemented per engine."
-        end
-        found
+        engine_file_problems(label, relative, File.read(File.join(root, relative)), declared)
       end
     end
 
+    # @return [Array<String>] the problems of one engine file: no `Comparison.holds?` call, and
+    #   a `when` case of its own for a declared comparator
+    def engine_file_problems(label, relative, source, declared)
+      found = []
+      unless source.include?("Comparison.holds?")
+        found << "#{relative} (#{label}) no longer calls Comparison.holds? at all — " \
+                 "has it grown its own comparator dispatch again?"
+      end
+      found + declared.filter_map { |comparator| own_case_problem(label, relative, source, comparator) }
+    end
+
+    # @return [String, nil] the problem when the engine file has its own `when` for the comparator
+    def own_case_problem(label, relative, source, comparator)
+      escaped = Regexp.escape(comparator)
+      return unless source =~ /when\s+"#{escaped}"/ || source =~ /when\s+:#{escaped}\b/
+
+      "#{relative} (#{label}) has its own `when #{comparator.inspect}` — comparator logic " \
+        "belongs ONLY in #{SHARED_COMPARISON_FILE}, not re-implemented per engine."
+    end
+
     # @param root [String] the checkout
     # @param declared [Array<String>] the declared comparators
     # @return [Array<String>] a problem for a comparator with no shared case, or no agreement spec
@@ -127,20 +134,20 @@ module Hecks
     def mentions_operator?(text, comparator)
       # Explicit form: the comparator as a bare hash key, bounded so `in:` cannot match
       # mid-identifier.
-      return true if text =~ /(?<![A-Za-z0-9_])#{Regexp.escape(comparator)}(?![A-Za-z0-9_])\s*:/
+      return true if /(?<![A-Za-z0-9_])#{Regexp.escape(comparator)}(?![A-Za-z0-9_])\s*:/.match?(text)
 
       # `eq` is normally implicit (`where(status: "open")`), so an example description naming it
       # counts; no other comparator gets that leniency.
       return false unless comparator == "eq"
 
-      text =~ /\b(?:it|describe)\s+"[^"]*\beq\b[^"]*"/i ? true : false
+      /\b(?:it|describe)\s+"[^"]*\beq\b[^"]*"/i.match?(text) || false
     end
 
     # @param finding [Finding] what a check found
     # @return [String] the clean-pass line
     def clean_line(finding)
       "check_engine_agreement: #{finding.declared.size} declared comparator(s) " \
-        "(#{finding.declared.sort.join(', ')}) — every one has a shared Comparison case, a cross-engine " \
+        "(#{finding.declared.sort.join(", ")}) — every one has a shared Comparison case, a cross-engine " \
         "agreement spec, and both engine files still route through Comparison.holds? alone. 0 problems."
     end
 

data/lib/hecks/forms/app/commands.rb

@@ -0,0 +1,98 @@
+require "json"
+require_relative "../command_form_renderer"
+require_relative "../params"
+require_relative "../../doors/command_request"
+require_relative "../../doors/json_door"
+
+module Hecks
+  module Forms
+    class App
+      # The command routes of `Forms::App`: the form, its submission, and the JSON door to the same
+      # dispatch.
+      module Commands
+        private
+
+        def command_route(request, domain, aggregate, command, format)
+          action = "/#{domain}/#{aggregate.hecks_name}/#{command.hecks_name}.html"
+          return command_json(request, domain, aggregate, command) if format != "html"
+          if request.get?
+            return command_form(domain, aggregate, command, action,
+                                prefill: receiver_compatibility(request.GET, command))
+          end
+          return respond(405, "text/plain", "GET or POST only") unless request.post?
+
+          submit_command(request, domain, aggregate, command, action)
+        end
+
+        # @param page [Hash] optionally `status:`, the submitted `values:`, the `error:` to show and
+        #   the `prefill:` values
+        def command_form(domain, aggregate, command, action, **page)
+          html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}",
+               CommandFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, command: command,
+                                          action: action, **page.slice(:values, :error, :prefill)),
+               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
+                             [command.hecks_name, nil]],
+               status:      page.fetch(:status, 200))
+        end
+
+        def submit_command(request, domain, aggregate, command, action)
+          raw, envelope = submitted_command(request, aggregate, command)
+          result = @dispatcher.dispatch_flat(verb_name(domain, aggregate, command), envelope)
+          # The id is free-form, so it is percent-encoded as a path segment.
+          redirect("/#{domain}/#{aggregate.hecks_name}/#{Escape.path(result.id)}.html")
+        rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
+          command_form(domain, aggregate, command, action, status: refusal_status(e), values: raw, error: e)
+        end
+
+        def command_json(request, domain, aggregate, command)
+          return json(200, command.to_h) if request.get? && request.GET.except("format").empty?
+          return respond(405, "text/plain", "GET or POST only") unless request.post?
+
+          created_json(request, domain, aggregate, command)
+        rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
+          refusal_json(e, refusal_status(e))
+        end
+
+        def created_json(request, domain, aggregate, command)
+          _, envelope = submitted_command(request, aggregate, command)
+          result = @dispatcher.dispatch_flat(verb_name(domain, aggregate, command), envelope)
+          # `id:` last, as in `aggregate_route`.
+          json(201, result.state.merge(id: result.id))
+        end
+
+        def verb_name(domain, aggregate, verb) = "#{domain}::#{aggregate.hecks_name}.#{verb.hecks_name}"
+
+        def command_envelope(command, args)
+          Doors::CommandRequest.normalize(args, receiver: command_receiver(command), legacy_receiver: :id)
+        end
+
+        def command_receiver(command) = command.creates? ? nil : :aggregate
+
+        def submitted_command(request, aggregate, command)
+          return submitted_json(request, command) if request.media_type == "application/json"
+
+          raw = receiver_compatibility(request.POST, command)
+          fields = CommandFormRenderer.fields_for(aggregate, command)
+          args = Params.extract(fields, raw)
+          [raw, command_envelope(command, args)]
+        end
+
+        def submitted_json(request, command)
+          raw = Doors::JsonDoor.parse(request.body.read)
+          envelope = Doors::JsonDoor.command_request(raw, receiver:        command_receiver(command),
+                                                          legacy_receiver: :id)
+          [raw, envelope]
+        end
+
+        # Existing integrations may still submit id. It remains an accepted
+        # edge spelling, but new forms expose only the receiver name to.
+        def receiver_compatibility(raw, command)
+          return raw if command.creates?
+          return raw unless raw.key?("id") && !raw.key?("to")
+
+          raw.merge("to" => raw["id"])
+        end
+      end
+    end
+  end
+end

data/lib/hecks/forms/app/queries.rb

@@ -0,0 +1,62 @@
+require "json"
+require_relative "../field_shape"
+require_relative "../params"
+require_relative "../query_form_renderer"
+
+module Hecks
+  module Forms
+    class App
+      # The query routes of `Forms::App`: the form with its results, and the JSON door to the same
+      # query.
+      module Queries
+        private
+
+        def query_route(request, domain, aggregate, query, format)
+          return respond(405, "text/plain", "GET only") unless request.get?
+
+          params = request.GET
+          asked = params.except("format")
+          return query_json(domain, aggregate, query, asked) if format != "html"
+
+          query_html(domain, aggregate, query, asked)
+        end
+
+        def query_html(domain, aggregate, query, asked)
+          action = "/#{domain}/#{aggregate.hecks_name}/#{query.hecks_name}.html"
+          results, error = asked.empty? ? [nil, nil] : run_query(domain, aggregate, query, asked)
+          html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}",
+               QueryFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, query: query,
+                                        action: action, params: asked, results: results, error: error),
+               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
+                             [query.hecks_name, nil]],
+               status:      error ? 422 : 200)
+        end
+
+        def query_json(domain, aggregate, query, asked)
+          return json(200, query.to_h) if asked.empty?
+
+          results, error = run_query(domain, aggregate, query, asked)
+          return refusal_json(error, 422) if error
+
+          # `id:` last, as in `aggregate_route`.
+          json(200, results.map { |i| i.state.merge(id: i.id) })
+        end
+
+        # `Dispatcher#query` answers plain hashes, not `Runtime::Instance`; wrapping them
+        # in `Record` gives the renderers one shape.
+        def run_query(domain, aggregate, query, asked)
+          fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
+          begin
+            args = Params.extract(fields, asked)
+            rows = @dispatcher.query("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}", **args)
+            [rows.map { |row| Record.new(row[:id], row.except(:id)) }, nil]
+          # `Params.extract` parses a list-of-value-object line as JSON; rescuing
+          # `JSON::ParserError` turns a malformed line into a 422 rather than a 500.
+          rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
+            [nil, e]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/forms/app/records.rb

@@ -0,0 +1,67 @@
+require_relative "../record_renderer"
+
+module Hecks
+  module Forms
+    class App
+      # The routes that list an aggregate's records or show one of them, in HTML or JSON.
+      module Records
+        private
+
+        def aggregate_route(request, chapter, aggregate_name, format)
+          aggregate = find_aggregate(chapter, aggregate_name)
+          return respond(405, "text/plain", "GET only") unless request.get?
+          return aggregate_json(chapter, aggregate) unless format == "html"
+
+          html("#{chapter.name}::#{aggregate.hecks_name}",
+               RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
+               breadcrumbs: [[chapter.name, "/"], [aggregate.hecks_name, nil]])
+        end
+
+        def aggregate_json(chapter, aggregate)
+          instances = @registry.repository(chapter.name, aggregate).all
+          # `id:` is merged last so an attribute named `id` in the state cannot clobber it.
+          json(200, instances.map { |i| i.state.merge(id: i.id) })
+        end
+
+        def verb_or_record_route(request, chapter, aggregate_name, verb_or_id, format)
+          aggregate = find_aggregate(chapter, aggregate_name)
+          domain = chapter.name
+
+          # A record id is free-form and can equal a verb name ("Close"), so a GET checks for
+          # a record first. POST never views a record, so it matches the verb first.
+          instance = request.get? && @registry.repository(domain, aggregate).find(verb_or_id)
+          return show_record(domain, aggregate, instance, verb_or_id, format) if instance
+
+          command = aggregate.command(verb_or_id)
+          return command_route(request, domain, aggregate, command, format) if command
+
+          query = aggregate.query(verb_or_id)
+          return query_route(request, domain, aggregate, query, format) if query
+
+          record_route(request, domain, aggregate, verb_or_id, format)
+        end
+
+        def record_route(request, domain, aggregate, id, format)
+          return respond(405, "text/plain", "GET only") unless request.get?
+
+          show_record(domain, aggregate, @registry.repository(domain, aggregate).find(id), id, format)
+        end
+
+        def show_record(domain, aggregate, instance, id, format)
+          return not_found(aggregate, id, format) unless instance
+          # `id:` last, as in `aggregate_route`.
+          return json(200, instance.state.merge(id: instance.id)) if format != "html"
+
+          html("#{domain}::#{aggregate.hecks_name} #{id}",
+               RecordRenderer.show(registry: @registry, domain: domain, aggregate: aggregate, id: id),
+               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
+                             [id, nil]])
+        end
+
+        def find_aggregate(chapter, name)
+          chapter.aggregate(name) || raise(RouteNotFound, "#{chapter.name} has no aggregate #{name.inspect}")
+        end
+      end
+    end
+  end
+end