hecks 5.0.0 → 7.0.0

data/lib/hecks/fixer/fixer.bluebook

@@ -0,0 +1,240 @@
+# The fixer: the work of taking a logged bug to a verified fix. QualityControl finds and records
+# bugs; this domain holds the attempts at them, and says what happened through its events.
+# A bug is never written here. QualityControl records each step from the events below.
+
+Hecks.bluebook "Fixer" do
+  vision "A logged bug gets one attempt at a time, each claimed, investigated, fixed and verified on the record, and the bug itself is only ever written by the quality ledger."
+
+  # One attempt at one logged bug. The attempt is keyed by the bug's reference, so there is at most
+  # one attempt for each bug the ledger has logged.
+  aggregate "Attempt" do
+    description "One attempt at one logged bug: who holds it, where the fault is, the commit that fixes it, and what verified it."
+
+    identified_by :reference
+
+    attribute :reference,    BugReference
+    attribute :held_by,      Engineer
+    attribute :claimed_at,   Instant
+    attribute :window,       StaleAfter
+    attribute :site,         BugSite, optional: true
+    attribute :cause,        BugCause, optional: true
+    attribute :commit,       CommitRef, optional: true
+    attribute :verification, Verification, optional: true
+    attribute :reproduction, ReproductionCommand, optional: true
+    attribute :observed,     ReproductionObserved, optional: true
+    attribute :reproduced,   ReproductionResult, optional: true
+    attribute :merged_commit, CommitRef, optional: true
+    attribute :merge_pending, MergePending, optional: true
+
+    value_object "BugReference" do
+      attribute :value, String, matches: :present
+      invariant("a bug is referenced") { !value.to_s.empty? }
+    end
+
+    value_object "BugSite" do
+      attribute :value, String, matches: :present
+      invariant("an investigation names where the bug lives") { !value.to_s.empty? }
+    end
+
+    value_object "BugCause" do
+      attribute :value, String, matches: :present
+      invariant("an investigation says why the code is wrong") { !value.to_s.empty? }
+    end
+
+    # 7 to 40 hex: a fix that lives only in a working tree is not a fix.
+    value_object "CommitRef" do
+      attribute :value, String, matches: :git_sha
+    end
+
+    # What was actually run, e.g. "rspec --order random, 1335 examples, 0 failures, seed 12345":
+    # a count and a seed are checkable, "tests pass" is not.
+    value_object "Verification" do
+      attribute :value, String, matches: :present
+      invariant("a verification says what was actually run") { !value.to_s.empty? }
+    end
+
+    # The exact command or entry point that was run, from the real path a user or caller takes.
+    # Verification must re-run this same text, so a fix that passes only new tests is not verified.
+    value_object "ReproductionCommand" do
+      attribute :value, String, matches: :present
+      invariant("a reproduction names the exact command run") { !value.to_s.empty? }
+    end
+
+    # A short fingerprint or the failing line the real path printed.
+    value_object "ReproductionObserved" do
+      attribute :value, String, matches: :present
+      invariant("a reproduction records what the real path printed") { !value.to_s.empty? }
+    end
+
+    value_object "ReproductionResult" do
+      attribute :value, String, matches: :present
+      invariant("a reproduction either failed or passed") { value == "failed" || value == "passed" }
+    end
+
+    # "yes" while a merged patch is on the record for an attempt that cannot yet record its fix.
+    value_object "MergePending" do
+      attribute :value, String, default: ""
+    end
+
+    value_object "Engineer" do
+      attribute :value, String, default: "nobody"
+    end
+
+    value_object "Instant" do
+      attribute :value, Integer, default: 0
+      invariant("an instant is not before the epoch") { !value.negative? }
+    end
+
+    value_object "StaleAfter" do
+      attribute :value, Integer, default: 900
+      invariant("a staleness window is positive") { value.positive? }
+    end
+
+    # A bug is born logged; each step moves the attempt along the same edges QualityControl uses.
+    lifecycle :status, default: "logged" do
+      transition "Investigate" => "investigating", from: %w[logged investigating]
+      transition "Fix"         => "fixed",         from: "investigating"
+      transition "Verify"      => "verified",      from: "fixed"
+      mark :terminal, "verified"
+    end
+
+    # The attempt is opened by the ledger's `BugLogged`, and nothing else creates one.
+    command "Open" do
+      role "Fixer"
+      goal "Start an attempt at a bug the ledger has logged, so it can be claimed"
+
+      attribute :reference, BugReference
+
+      emits "AttemptOpened"
+    end
+
+    # Same rule as QualityControl's `Bug.Claim`: held by nobody, or stale.
+    command "Claim" do
+      role "Fixer"
+      goal "Take the attempt, or one whose holder has gone quiet"
+
+      reference_to Attempt
+      attribute :reference, BugReference
+      attribute :held_by,   Engineer, sets: true
+      attribute :now,       Instant
+      needs :now
+
+      given("a live claim is not taken from the agent holding it") do
+        held_by.value == "nobody" || claimed_at.value + window.value <= now.value
+      end
+
+      sets :claimed_at, to: :now
+
+      emits "AttemptClaimed"
+    end
+
+    # An investigation starts from the real entry point: the command run, what it printed, and
+    # whether it failed. `Fix` is refused until a failing reproduction is on the record. An
+    # attempt already investigating can be investigated again, to record the reproduction it lacks
+    # or to replace one that did not fail.
+    command "Investigate" do
+      role "Fixer"
+      goal "Run the real entry point, record its failure, name the code that is wrong and say why"
+
+      reference_to Attempt
+      attribute :reference,    BugReference
+      attribute :site,         BugSite,  sets: true
+      attribute :cause,        BugCause, sets: true
+      attribute :reproduction, ReproductionCommand,  sets: true
+      attribute :observed,     ReproductionObserved, sets: true
+      attribute :reproduced,   ReproductionResult,   sets: true
+
+      emits "AttemptInvestigated"
+    end
+
+    # `FixReady` carries the commit that makes the bug stop happening. The ledger records the fixed
+    # state from it, and the commit is what the Clearance check and the saga correlate on.
+    command "Fix" do
+      role "Fixer"
+      goal "Record the commit that makes it stop happening"
+
+      reference_to Attempt
+      attribute :reference, BugReference
+      attribute :commit,    CommitRef, sets: true
+
+      given("no failing reproduction recorded: run the real entry point first") do
+        !reproduction.nil? && !reproduced.nil? && reproduced.value == "failed"
+      end
+
+      emits "FixReady"
+    end
+
+    # A merged patch the attempt cannot yet record as its fix (no failing reproduction on the
+    # record) is kept on the attempt and announced, so it is neither dropped nor silent: the
+    # attempt lists under `AwaitingReproduction` until it is investigated and fixed.
+    command "NoteMerge" do
+      role "Fixer"
+      goal "Keep a merged patch that the attempt cannot yet record as its fix"
+
+      reference_to Attempt
+      attribute :reference, BugReference
+      attribute :commit,    CommitRef
+
+      given("a patch the attempt already recorded as its fix is not pending") do
+        reproduction.nil? || reproduced.nil? || reproduced.value != "failed"
+      end
+
+      sets :merged_commit, to: :commit
+      sets :merge_pending, to: "yes"
+
+      emits "MergeAwaitsReproduction"
+    end
+
+    # The attempts holding a merged patch they could not record: the QA tick reads these, investigates
+    # with a failing reproduction, then records the fix with `merged_commit`.
+    query "AwaitingReproduction" do
+      description "Every attempt with a merged patch it could not record as its fix because no failing reproduction is on the record."
+      where(status: { in: "logged,investigating" }, merge_pending: "yes")
+      order_by :claimed_at
+    end
+
+    # `FixVerified` restates the reference and commit so the ledger can record the verified state
+    # against the bug it names.
+    command "Verify" do
+      role "Fixer"
+      goal "Record that the fix was actually verified, and exactly how"
+
+      reference_to Attempt
+      attribute :reference, BugReference
+      attribute :commit,    CommitRef
+      attribute :evidence,  Verification
+      attribute :rerun,         ReproductionCommand
+      attribute :rerun_result,  ReproductionResult
+
+      given("the reproduction re-run is not the one recorded: run the recorded command") do
+        !reproduction.nil? && rerun.value == reproduction.value
+      end
+
+      given("the recorded reproduction still fails: a fix that passes only new tests is not verified") do
+        rerun_result.value == "passed"
+      end
+
+      sets :verification, to: :evidence
+
+      emits "FixVerified"
+    end
+  end
+
+  # The ledger logged a bug: the attempt at it is opened, ready to be claimed.
+  policy "OpenOnBugLogged" do
+    on      "Bug.BugLogged"
+    trigger Attempt::Open, with: { reference: :reference }
+  end
+
+  # A merged patch is the commit that makes a bug's fix true, so the attempt at it records the fix.
+  policy "FixOnPatchMerged" do
+    on      "Patch.PatchMerged"
+    trigger Attempt::Fix, with: { reference: :bug, commit: :commit }
+  end
+
+  # Declared after the fix: an attempt that could not record it keeps the commit and says so.
+  policy "NoteMergeWhenPatchMerged" do
+    on      "Patch.PatchMerged"
+    trigger Attempt::NoteMerge, with: { reference: :bug, commit: :commit }
+  end
+end

data/lib/hecks/fixer/fixer.hecksagon

@@ -0,0 +1,17 @@
+# The Fixer domain, bound so it boots standing alone (a fuzz or model_check boot of this
+# directory). The attempts are held in Memory here; the ledger's own store is wired by the
+# QualityControl hecksagon.
+Hecks.hecksagon "Fixer" do
+  attaches "Governance"
+  persisted_by "Memory"
+
+  # The ledger's bug being logged, which opens the attempt at it, and a merged patch, which records
+  # the fix. Declarative: QualityControl emits both, and the policies above react.
+  subscribe "QualityControl.BugLogged"
+  subscribe "QualityControl.PatchMerged"
+end
+
+# The anti-corruption layer for Governance, which the bluebook's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

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

@@ -3,6 +3,7 @@ require_relative "../command_form_renderer"
 require_relative "../params"
 require_relative "../../adapters/driving/command_request"
 require_relative "../../adapters/driving/json"
+require_relative "../../projections/command_schema"
 
 module Hecks
   module Forms
@@ -11,6 +12,9 @@ module Hecks
       # same
       # dispatch.
       module Commands
+        # The values of `dry_run=` / `X-Dry-Run:` that ask for a validation instead of a dispatch.
+        DRY_RUN_FLAGS = %w[1 true].freeze
+
         private
 
         def command_route(request, domain, aggregate, command, format)
@@ -45,14 +49,42 @@ module Hecks
         end
 
         def command_json(request, domain, aggregate, command)
-          return json(200, command.to_h) if request.get? && request.GET.except("format").empty?
+          return command_read_json(request, domain, aggregate, command) if request.get?
           return respond(405, "text/plain", "GET or POST only") unless request.post?
+          return validated_json(request, domain, aggregate, command) if dry_run_requested?(request)
 
           created_json(request, domain, aggregate, command)
         rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
           refusal_json(e, refusal_status(e))
         end
 
+        # A GET of a command's JSON route: its descriptor, or with `?schema=1` its JSON Schema.
+        def command_read_json(request, domain, aggregate, command)
+          return command_schema(domain, aggregate, command) if request.GET["schema"] == "1"
+          return json(200, command.to_h) if request.GET.except("format").empty?
+
+          respond(405, "text/plain", "GET or POST only")
+        end
+
+        # The JSON Schema of the facts the command takes (`?schema=1`), with the rules a schema
+        # cannot hold as `x-` annotations.
+        def command_schema(domain, aggregate, command)
+          path = "#{aggregate.hecks_name}/#{command.hecks_name}"
+          json(200, Projections::CommandSchema.document(@registry.bluebook(domain), aggregate, path, command))
+        end
+
+        # Whether the request asks to be validated, not carried out: `?dry_run=1` or `X-Dry-Run: 1`.
+        def dry_run_requested?(request)
+          DRY_RUN_FLAGS.include?(request.GET["dry_run"].to_s) || DRY_RUN_FLAGS.include?(request.get_header("HTTP_X_DRY_RUN").to_s)
+        end
+
+        # The same body, caller and route as the real command, answered as every reason it would be
+        # refused. A completed validation is a 200 whether or not it refused.
+        def validated_json(request, domain, aggregate, command)
+          _, envelope = submitted_command(request, aggregate, command)
+          json(200, @dispatcher.validate(verb_name(domain, aggregate, command), envelope).to_h)
+        end
+
         def created_json(request, domain, aggregate, command)
           _, envelope = submitted_command(request, aggregate, command)
           result = @dispatcher.dispatch_flat(verb_name(domain, aggregate, command), envelope)
@@ -78,7 +110,8 @@ module Hecks
         end
 
         def submitted_json(request, command)
-          raw = Adapters::Driving::Json.parse(request.body.read)
+          body = request.body
+          raw = Adapters::Driving::Json.parse(body.read)
           envelope = Adapters::Driving::Json.command_request(raw, receiver:        command_receiver(command),
                                                                   legacy_receiver: :id)
           [raw, envelope]

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

@@ -7,25 +7,25 @@ module Hecks
       module Records
         private
 
-        def aggregate_route(request, chapter, aggregate_name, format)
-          aggregate = find_aggregate(chapter, aggregate_name)
+        def aggregate_route(request, declaration, aggregate_name, format)
+          aggregate = find_aggregate(declaration, aggregate_name)
           return respond(405, "text/plain", "GET only") unless request.get?
-          return aggregate_json(chapter, aggregate) unless format == "html"
+          return aggregate_json(declaration, aggregate) unless format == "html"
 
           html(Naming.plural(Humanize.phrase(aggregate.hecks_name)),
-               RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
-               breadcrumbs: [[chapter.name, "/"], [Humanize.phrase(aggregate.hecks_name), nil]])
+               RecordRenderer.index(registry: @registry, domain: declaration.name, aggregate: aggregate),
+               breadcrumbs: [[declaration.name, "/"], [Humanize.phrase(aggregate.hecks_name), nil]])
         end
 
-        def aggregate_json(chapter, aggregate)
-          instances = @registry.repository(chapter.name, aggregate).all
+        def aggregate_json(declaration, aggregate)
+          instances = @registry.repository(declaration.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
+        def verb_or_record_route(request, declaration, aggregate_name, verb_or_id, format)
+          aggregate = find_aggregate(declaration, aggregate_name)
+          domain = declaration.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.
@@ -70,8 +70,8 @@ module Hecks
           aggregate_crumbs(domain, aggregate) + [[Humanize.phrase(verb.hecks_name), nil]]
         end
 
-        def find_aggregate(chapter, name)
-          chapter.aggregate(name) || raise(RouteNotFound, "#{chapter.name} has no aggregate #{name.inspect}")
+        def find_aggregate(declaration, name)
+          declaration.aggregate(name) || raise(RouteNotFound, "#{declaration.name} has no aggregate #{name.inspect}")
         end
       end
     end

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

@@ -31,7 +31,7 @@ module Hecks
         def refusal_status(error) = error.is_a?(Runtime::NotFound) ? 404 : 422
 
         def refusal_json(error, status)
-          json(status, { error: error.class.name.split("::").last, message: error.message })
+          json(status, { error: Naming.demodulise(error.class.name), message: error.message })
         end
 
         def not_found(aggregate, id, format)

data/lib/hecks/forms/app.rb

@@ -16,12 +16,15 @@ module Hecks
       include Commands
       include Queries
 
-      # Builds the Rack app for a configured app name, exposing exactly the chapters its
+      # A path segment ending in a format extension, capturing the rest and the format.
+      FORMAT_SUFFIX = /\A(.*)\.(html|json)\z/
+
+      # Builds the Rack app for a configured app name, exposing exactly the bluebooks its
       # `Forms.configure` block declared.
       #
-      # @param registry [Runtime::Registry] the booted registry holding the exposed chapters
+      # @param registry [Runtime::Registry] the booted registry holding the exposed bluebooks
       # @param app_name [String, Symbol] the name an earlier `Forms.configure` call registered
-      # @return [Forms::App] a Rack app routing only the configured chapters
+      # @return [Forms::App] a Rack app routing only the configured bluebooks
       # @raise [ArgumentError] if no app of that name has been configured
       def self.for(registry:, app_name:)
         config = Forms.config(app_name) ||
@@ -30,8 +33,8 @@ module Hecks
         new(registry: registry, exposed: config.exposes)
       end
 
-      # @param registry [Runtime::Registry] the booted registry holding the exposed chapters
-      # @param exposed [Array<String>] names of the chapters (domains) this app routes; a
+      # @param registry [Runtime::Registry] the booted registry holding the exposed bluebooks
+      # @param exposed [Array<String>] names of the bluebooks (domains) this app routes; a
       #   request for any other domain is answered 404
       # @param dispatcher [Runtime::Dispatcher, nil] the dispatcher commands and queries go
       #   through; nil builds a `Runtime::Dispatcher` over `registry`
@@ -62,26 +65,26 @@ module Hecks
         segments = request.path_info.split("/").reject(&:empty?)
         return home(request) if segments.empty?
 
-        chapter = chapter_for(segments[0])
+        declaration = bluebook_for(segments[0])
         case segments.size
-        when 2 then aggregate_route(request, chapter, *split_format(segments[1]))
-        when 3 then verb_or_record_route(request, chapter, segments[1], *split_format(segments[2]))
-        else unrouted(request, chapter, segments)
+        when 2 then aggregate_route(request, declaration, *split_format(segments[1]))
+        when 3 then verb_or_record_route(request, declaration, segments[1], *split_format(segments[2]))
+        else unrouted(request, declaration, segments)
         end
       end
 
-      def unrouted(request, chapter, segments)
-        refuse_entity_command if segments.size == 4 && entity_command?(chapter, segments)
+      def unrouted(request, declaration, segments)
+        refuse_entity_command if segments.size == 4 && entity_command?(declaration, segments)
         respond(404, "text/plain", "no route for #{request.path_info}")
       end
 
-      def chapter_for(domain)
+      def bluebook_for(domain)
         refuse_unexposed(domain)
         @registry.bluebook(domain) || raise(RouteNotFound, "no domain #{domain.inspect} loaded")
       end
 
-      def entity_command?(chapter, segments)
-        entity = chapter.aggregate(segments[1])&.entities&.find { |candidate| candidate.hecks_name == segments[2] }
+      def entity_command?(declaration, segments)
+        entity = declaration.aggregate(segments[1])&.entities&.find { |candidate| candidate.hecks_name == segments[2] }
         !entity&.command(split_format(segments[3]).first).nil?
       end
 
@@ -94,24 +97,24 @@ module Hecks
       def refuse_unexposed(domain)
         return if @exposed.include?(domain)
 
-        raise RouteNotFound, "#{domain.inspect} is not exposed by this app — declared chapters: #{@exposed.join(", ")}"
+        raise RouteNotFound, "#{domain.inspect} is not exposed by this app — declared bluebooks: #{@exposed.join(", ")}"
       end
 
       # Only a trailing ".html"/".json" is a format; other dots belong to the identity
       # (an email, say). An identity ending in ".html" or ".json" stays ambiguous.
       def split_format(segment)
         segment = segment.to_s
-        return [Regexp.last_match(1), Regexp.last_match(2)] if segment =~ /\A(.*)\.(html|json)\z/
+        return [Regexp.last_match(1), Regexp.last_match(2)] if segment =~ FORMAT_SUFFIX
 
         [segment, "json"]
       end
 
       def home(request)
         format = request.params["format"] || "html"
-        chapters = @exposed.to_h { |name| [name, @registry.bluebook(name)] }.compact
-        return json(200, chapters.transform_values { |c| { aggregates: c.aggregates.map(&:hecks_name) } }) if format != "html"
+        declarations = @exposed.to_h { |name| [name, @registry.bluebook(name)] }.compact
+        return json(200, declarations.transform_values { |c| { aggregates: c.aggregates.map(&:hecks_name) } }) if format != "html"
 
-        html("Exposed domains", IndexRenderer.render(chapters))
+        html("Exposed domains", IndexRenderer.render(declarations))
       end
     end
   end

data/lib/hecks/forms/command_form_renderer.rb

@@ -147,7 +147,7 @@ module Hecks
 
         <<~HTML
           <div class="error-banner" role="alert">
-            <p><strong>Refused (#{Escape.html(error.class.name.split("::").last)}):</strong> #{Escape.html(error.message)}</p>
+            <p><strong>Refused (#{Escape.html(Naming.demodulise(error.class.name))}):</strong> #{Escape.html(error.message)}</p>
           </div>
         HTML
       end
@@ -165,7 +165,7 @@ module Hecks
       # Renders the collapsed "Inspect" panel: the events the command emits, an equivalent
       # `curl` request, its field paths, and its declaration as JSON.
       #
-      # @param domain [String] name of the domain (chapter) the aggregate belongs to
+      # @param domain [String] name of the domain (bluebook) the aggregate belongs to
       # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
       # @param command [Bluebook::Command] the command being described
       # @param action [String] URL path the form posts to, shown in the `curl` line

data/lib/hecks/forms/field_controls.rb

@@ -1,4 +1,5 @@
 require_relative "html"
+require_relative "html_pattern"
 require_relative "../naming"
 
 module Hecks
@@ -23,7 +24,11 @@ module Hecks
         end
 
         # A :reference input takes a record id, so the attribute's own pattern must not apply.
-        def self.leaf_pattern(field) = field.kind == :reference ? nil : field.pattern
+        def self.leaf_pattern(field) = field.kind == :reference ? nil : html_pattern(field.pattern)
+
+        # @param pattern [String, nil] the attribute's pattern
+        # @return [String, nil] the pattern as the input should carry it (see `HtmlPattern`)
+        def self.html_pattern(pattern) = HtmlPattern.for(pattern)
 
         def self.preview_target(field) = "##{FieldRenderer.dom_id(field.path)}-preview"
 

data/lib/hecks/forms/field_shape.rb

@@ -24,10 +24,17 @@ module Hecks
 
     # Turns a wire-spelled field or path segment into a label or legend.
     module Humanize
+      # A leading run of two or more capitals: an acronym that keeps its case.
+      LEADING_ACRONYM = /\A[A-Z]{2,}\b/
+
+      # The first character of a phrase.
+      FIRST_CHARACTER = /\A./
+
       # "daily_limit" -> "Daily limit"; only the last segment of a dotted path is used.
       def self.label(text)
         # Split on "." alone: an underscore is a word break within a segment, not a path hop.
-        segment = text.to_s.split(".").last.to_s
+        segments = text.to_s.split(".")
+        segment = segments.last.to_s
         return segment if segment.empty?
 
         Naming.words(segment)
@@ -46,7 +53,7 @@ module Hecks
       # @return [String] the words, the first lowercased unless it is an acronym
       def self.noun(name)
         words = Naming.words(name)
-        words.match?(/\A[A-Z]{2,}\b/) ? words : words.sub(/\A./, &:downcase)
+        words.match?(LEADING_ACRONYM) ? words : words.sub(FIRST_CHARACTER, &:downcase)
       end
     end
 
@@ -57,7 +64,7 @@ module Hecks
       # Resolves one declared attribute into the field a form renders for it.
       #
       # `aggregate` owns the attribute and is needed to resolve `reference_to`, `admits:`
-      # and same-chapter value objects; `path` is the dotted path reached so far.
+      # and same-bluebook value objects; `path` is the dotted path reached so far.
       #
       # @param attribute [Bluebook::Attribute]
       # @param aggregate [Bluebook::Aggregate]
@@ -90,12 +97,12 @@ module Hecks
       end
 
       def self.reference_field(attribute, common)
-        target = attribute.type.resolve
+        target = attribute.target_aggregate
         help = target ? "An existing #{Humanize.noun(target.hecks_name)}, by its id." : "A record in another domain, by its id."
         Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target, help: help)
       end
 
-      # Mirrors Runtime::Value::Admission#admitted_members (same split, chapter walk and
+      # Mirrors Runtime::Value::Admission#admitted_members (same split, bluebook walk and
       # discriminant rule) so a `<select>` never offers a member the runtime would refuse.
       def self.admitted_field(attribute, aggregate, common)
         set = admitted_set(attribute, aggregate)
@@ -148,7 +155,8 @@ module Hecks
       end
 
       def self.cross_aggregate_value_object(aggregate, type_name)
-        aggregate.hecks_owner&.aggregates&.each do |sibling|
+        owner = aggregate.hecks_owner
+        owner&.aggregates&.each do |sibling|
           found = sibling.value_object(type_name)
           return found if found
         end

data/lib/hecks/forms/html.rb

@@ -5,20 +5,21 @@ module Hecks
     # HTML, URL-query and URL-path escaping for values that come from domain data.
     # Nothing that reaches `Escape.html` becomes a tag.
     module Escape
+      # A character HTML text content must not hold as itself.
+      HTML_SPECIAL = /[&<>"']/
+
+      # The entity each `HTML_SPECIAL` character is written as.
+      HTML_ENTITIES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "'" => "&#39;" }.freeze
+
       # Escapes a value for HTML text content, replacing `&`, `<`, `>`, `"` and `'` with
       # entities so nothing in it becomes a tag.
       #
-      # `&` is replaced first so the entities written here are not escaped again.
+      # One pass over the text, so the entities written here are not escaped again.
       #
       # @param value [Object, nil] the value to show, rendered with `to_s`; nil renders as `""`
       # @return [String] the escaped text
       def self.html(value)
-        value.to_s
-             .gsub("&", "&amp;")
-             .gsub("<", "&lt;")
-             .gsub(">", "&gt;")
-             .gsub('"', "&quot;")
-             .gsub("'", "&#39;")
+        value.to_s.gsub(HTML_SPECIAL, HTML_ENTITIES)
       end
 
       # Escapes a value for use inside a quoted HTML attribute.