hecks 5.0.0 → 7.0.0

data/lib/hecks/projections/deploy/smoke.rb

@@ -27,6 +27,8 @@ module Hecks
           setup:        /\A[^\r\n]+\z/
         }.freeze
         REQUIRED = %i[role_arn secret_id site_url region].freeze
+        # The template line that holds the setup step.
+        SETUP_LINE = /^@@setup@@\n/
 
         module_function
 
@@ -82,7 +84,7 @@ module Hecks
 
         # A placeholder line that resolves to nothing disappears whole, not as a blank line.
         def render(template, values)
-          filled = template.gsub(/^@@setup@@\n/) { setup_step(values[:setup]) }
+          filled = template.gsub(SETUP_LINE) { setup_step(values[:setup]) }
           filled = filled.gsub("@@secret_field_pipe@@") { secret_field_pipe(values[:secret_field]) }
           values.except(:setup, :secret_field).each { |key, value| filled = filled.gsub("@@#{key}@@") { value.to_s } }
           raise ArgumentError, "unfilled placeholder in the smoke workflow" if filled.include?("@@")

data/lib/hecks/projections/deploy/template_diff/normalizer.rb

@@ -8,6 +8,9 @@ module Hecks
         module Normalizer
           module_function
 
+          # A `!Sub` string that is one whole variable, `${Name}` or `${A.B}`, capturing its name.
+          WHOLE_VARIABLE = /\A\$\{([^}!]+)\}\z/
+
           # @param value [Object] a loaded template, or any node inside one
           # @return [Object] the same shape with every node in its canonical spelling
           def normalize(value)
@@ -40,7 +43,7 @@ module Hecks
             text = hash["Fn::Sub"]
             return text unless text.include?("${")
 
-            match = text.match(/\A\$\{([^}!]+)\}\z/)
+            match = text.match(WHOLE_VARIABLE)
             return hash unless match
 
             intrinsic_for(match[1])

data/lib/hecks/projections/deploy/templates/fargate/Makefile.tmpl

@@ -35,7 +35,7 @@ build:
 # generator the Lambda deploy path already uses to produce
 # rust/dist/@@domain_name@@.wasm/.ir.json from this domain's own
 # .bluebook.
-	cd $(ROOT) && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm domain=$(DOMAIN) --wait
+	cd $(ROOT) && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm! domain=$(DOMAIN) --wait
 	cd $(HOST_DIR) && CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc rustup run stable cargo build --release --target aarch64-unknown-linux-gnu --bin bootstrap
 	cp $(HOST_DIR)/target/aarch64-unknown-linux-gnu/release/bootstrap @@domain_name@@-host
 	cp $(ROOT)/rust/dist/@@domain_name@@.wasm @@domain_name@@.wasm

data/lib/hecks/projections/deploy/templates/lambda/Makefile.tmpl

@@ -27,7 +27,7 @@ build-@@logical_id@@:
 # field). `hecks build_wasm` recompiles fast enough that "always
 # rebuild" is the safe default, matching rust/host's own bootstrap
 # build just below, which was never guarded this way to begin with.
-	cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm domain=@@domain@@ --wait
+	cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm! domain=@@domain@@ --wait
 	@rustup target list --installed 2>/dev/null | grep -qx aarch64-unknown-linux-gnu || rustup target add aarch64-unknown-linux-gnu
 # `rustup run stable`, not a bare `cargo lambda` — same reasoning
 # `hecks build_wasm`'s own Makefile-equivalent line holds itself to: a
@@ -129,12 +129,12 @@ restore-@@logical_id@@-build:
 .PHONY: verify-parity-@@logical_id@@
 verify-parity-@@logical_id@@:
 	@if [ -f @@root@@/spec/corpus/@@domain_name@@.json ]; then \
-		cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.check_conformance domain=@@domain@@ script=spec/corpus/@@domain_name@@.json artifact=$(WASM) --wait; \
+		cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.check_conformance! domain=@@domain@@ script=spec/corpus/@@domain_name@@.json artifact=$(WASM) --wait; \
 	else \
 		echo "verify-parity-@@logical_id@@: no spec/corpus/@@domain_name@@.json -- SKIPPING the pre-deploy Ruby/Rust parity check, nothing to compare $(WASM) against. Write one (hecks fuzz/hecks run's own script shape) before this domain's next deploy."; \
 	fi
 	@echo "verify-parity-@@logical_id@@: fuzzing $(WASM) against generated sequences (ADR 0037's bridge, WARN-ONLY -- see this target's own comment)..."
-	-@cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.fuzz_conformance domain=@@domain@@ artifact=$(WASM) --wait
+	-@cd @@root@@ && HECKS_ENVIRONMENT=memory ruby exe/hecks build.fuzz_conformance! domain=@@domain@@ artifact=$(WASM) --wait
 
 # `make mint-era` — takes @@stack_name@@'s RDS instance from freshly
 # created to "era 1 minted, ready for HECKS_DOMAIN/HECKS_ERA to

data/lib/hecks/projections/deploy/templates/lambda/mint_era_shared.tmpl

@@ -12,7 +12,7 @@
 # for a domain with its own dedicated instance.
 #
 # IF THIS DOMAIN VENDORS/ATTACHES ANOTHER BLUEBOOK (attaches,
-# attaches ... from: :vendor), `check!` alone leaves THAT chapter's own
+# attaches ... from: :vendor), `check!` alone leaves THAT bluebook's own
 # aggregates with no snapshot table at all -- it only provisions the
 # ONE bluebook it's called with (era_resolver.rb's own `bluebook.
 # aggregates.each`), never the whole registry. Found live minting
@@ -21,7 +21,7 @@
 # time this domain's own checkout route ran for real. The automated
 # (non-Shared) recipe below now does this correctly for every OTHER
 # loaded bluebook, using ONE `Lineage` keyed by THIS domain's own
-# name (never each chapter's own -- a vendored chapter's aggregates
+# name (never each bluebook's own -- a vendored bluebook's aggregates
 # share THIS domain's single `hecks_journal_@@infra_name@@` and
 # snapshot tables, they do not get a separate journal of their own).
 # Reproduce the same shape manually here: after `LineageManager.

data/lib/hecks/projections/deploy/templates/lambda/nat_comment_oauth.tmpl

@@ -1,6 +1,6 @@
   #
   # @@web_logical_id@@ is the ONE exception -- real Google OAuth token
-  # exchange (the Rust web host's Google sign-in posting to
+  # exchange (hecks's own GoogleAuthentication adapter posting to
   # https://oauth2.googleapis.com/token) is a genuine third-party HTTPS
   # call with no AWS PrivateLink/VPC Endpoint option (unlike
   # lambda:InvokeFunction, above), and @@web_logical_id@@ is ALSO

data/lib/hecks/projections/deploy/vercel.rb

@@ -29,7 +29,7 @@ module Hecks
 
         module_function
 
-        # @param bluebook [Bluebook::Behaviour::Chapter] the domain's own booted chapter
+        # @param bluebook [Bluebook::Behaviour::Bluebook] the domain's own booted bluebook
         # @param options [Hash] generation options; same shape as `Box.call`'s
         # @return [Hash{String => String}] the generated file contents, keyed by filename
         # @raise [ArgumentError] if the domain's deploy settings are invalid

data/lib/hecks/projections/diagrams/dispatch.rb

@@ -6,7 +6,7 @@ module Hecks
       module Dispatch
         module_function
 
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @return [String, nil] commands, the events they emit and the policies those trigger,
         #   or nil when there are none
         def dispatch_diagram(bluebook)
@@ -31,12 +31,14 @@ module Hecks
 
         # `on_event` may be aggregate-qualified while `emits` never is, so match on the bare tail.
         def trigger_edge(policy)
-          bare_event = policy.on_event.to_s.split(".").last
+          bare_event = last_segment(policy.on_event)
           aggregate_name, command_name = policy.trigger_command.to_s.split(".", 2)
           label = policy.target_domain ? "triggers in #{policy.target_domain}" : "triggers"
           %(    #{event_node(bare_event)} -->|#{label}| #{command_node(aggregate_name, command_name)})
         end
 
+        def last_segment(dotted) = Naming.last_segment(dotted)
+
         # Qualified by aggregate since two aggregates may share a command name.
         #
         # @param aggregate_name [String] the aggregate or entity that holds the command
@@ -50,7 +52,7 @@ module Hecks
         # @return [String] its Mermaid node
         def event_node(event_name) = %(evt_#{event_name}{{"#{event_name}"}})
 
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @param holder [Object] an aggregate or entity with commands or queries
         # @return [String] what the holder does, writes and answers
         def surface_diagram(bluebook, holder)

data/lib/hecks/projections/diagrams/statecharts.rb

@@ -5,7 +5,7 @@ module Hecks
       module Statecharts
         module_function
 
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @param holder [Object] an aggregate or entity with a lifecycle
         # @return [String] the lifecycle's states and the commands that move between them
         def lifecycle_diagram(bluebook, holder)
@@ -22,7 +22,7 @@ module Hecks
           MERMAID
         end
 
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @param saga [Object] a process manager
         # @return [String] the saga's states and what each transition dispatches
         def saga_diagram(bluebook, saga)
@@ -51,7 +51,12 @@ module Hecks
 
         # Listed in declaration order; at refusal the runtime fires them newest first.
         def derived_compensations(saga)
-          saga.handlers.flat_map { |handler| handler.dispatches.filter_map { |dispatch| dispatch.compensates&.command_name } }
+          saga.handlers.flat_map { |handler| handler.dispatches.filter_map { |dispatch| compensating_command(dispatch) } }
+        end
+
+        def compensating_command(dispatch)
+          compensation = dispatch.compensates
+          compensation&.command_name
         end
       end
     end

data/lib/hecks/projections/diagrams/structure.rb

@@ -6,10 +6,13 @@ module Hecks
       module Structure
         module_function
 
+        # A run of characters a Mermaid node id may not hold.
+        NOT_ID_CHARACTERS = /[^A-Za-z0-9]+/
+
         # `has_many`/`has_one` read from the owning side; `belongs_to`/`reference_to` read
         # from the target's side, since a bare reference does not promise uniqueness.
         #
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @return [String, nil] the entity-relationship diagram, or nil without references
         def relationship_diagram(bluebook)
           edges = Diagrams.holders(bluebook).flat_map do |holder|
@@ -22,7 +25,7 @@ module Hecks
         end
 
         def relationship_edge(holder, attribute)
-          target = attribute.type.target_name
+          target = attribute.target_name
           case attribute.relationship
           when "has_many"
             %(    #{holder.hecks_name} ||--o{ #{target} : "#{attribute.name}")
@@ -33,7 +36,7 @@ module Hecks
           end
         end
 
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @return [String, nil] who issues which command, or nil when no command names a role
         def roles_diagram(bluebook)
           lines = Diagrams.holders(bluebook).flat_map do |holder|
@@ -52,11 +55,11 @@ module Hecks
 
         # A role is free text ("Back office"), so only its id is sanitized; the label keeps
         # the text.
-        def role_id(role_name) = "role_#{role_name.to_s.gsub(/[^A-Za-z0-9]+/, "_")}"
+        def role_id(role_name) = "role_#{role_name.to_s.gsub(NOT_ID_CHARACTERS, "_")}"
 
         # Walks `bluebook.aggregates`, not `holders`: an entity has no `ports` method.
         #
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @return [String, nil] the port operations, or nil when no aggregate has a port
         def ports_diagram(bluebook)
           lines = bluebook.aggregates.flat_map do |holder|
@@ -81,7 +84,7 @@ module Hecks
           %(#{id}[/"#{port_name}.#{operation_name}"/])
         end
 
-        # @param bluebook [Bluebook::Chapter] the assembled chapter
+        # @param bluebook [Bluebook::Declaration] the assembled bluebook
         # @return [String, nil] each read model and its source aggregates, or nil without any
         def read_model_diagram(bluebook)
           lines = bluebook.read_models.flat_map { |read_model| read_model_edges(read_model) }

data/lib/hecks/projections/diagrams.rb

@@ -17,7 +17,7 @@ module Hecks
       # Projects one domain's whole shape into every diagram kind it has data
       # for, one Mermaid file per entry.
       #
-      # @param bluebook [Bluebook::Chapter] the assembled chapter to project
+      # @param bluebook [Bluebook::Declaration] the assembled bluebook to project
       # @param options [Hash{Symbol => Object}] projection options; only `:hecksagon`
       #   (a `Bluebook::Hecksagon`, or `nil`) is read, and only by `frameworks_diagram`
       # @return [Hash{String => String}] each diagram's filename (such as
@@ -37,12 +37,12 @@ module Hecks
 
       def holders_with_lifecycle(bluebook) = holders(bluebook).select(&:lifecycle)
 
-      # `chapter_name` drives the re-run hint: `hecks project_diagrams` takes a chapter
+      # `declaration_name` drives the re-run hint: `hecks project_diagrams` takes a bluebook
       # name, not the subject's.
-      def header(chapter_name, subject)
+      def header(declaration_name, subject)
         <<~HEADER
           %% GENERATED by hecks project_diagrams from #{subject} — DO NOT EDIT BY HAND.
-          %% Re-run `hecks project_diagrams <domain-path> #{chapter_name}` after any change.
+          %% Re-run `hecks project_diagrams <domain-path> #{declaration_name}` after any change.
         HEADER
       end
 
@@ -87,11 +87,13 @@ module Hecks
       end
 
       def framework_edges(bluebook, hecksagon)
-        attached = hecksagon.member_chapters.map { |name| domain_edge(bluebook.name, "attaches", name, dotted: true) }
-        attached + bluebook.policies.filter_map(&:target_domain).uniq
-                           .map { |name| domain_edge(bluebook.name, "reaches across", name, dotted: false) }
+        attached = hecksagon.member_bluebooks.map { |name| domain_edge(bluebook.name, "attaches", name, dotted: true) }
+        attached + policy_target_domains(bluebook)
+                   .map { |name| domain_edge(bluebook.name, "reaches across", name, dotted: false) }
       end
 
+      def policy_target_domains(bluebook) = bluebook.policies.filter_map(&:target_domain).uniq
+
       def domain_edge(from, label, to, dotted:)
         arrow = dotted ? "-.->" : "-->"
         %(    #{from}[(#{from})] #{arrow}|#{label}| #{to}[(#{to})])

data/lib/hecks/projections/glossary/entries.rb

@@ -1,14 +1,14 @@
 module Hecks
   module Projections
     module Glossary
-      # Gathers every term a chapter's glossary carries, one `Entry` for each, ungrouped and
+      # Gathers every term a bluebook's glossary carries, one `Entry` for each, ungrouped and
       # unordered.
       module Entries
         module_function
 
         # Entities carry their own commands and queries, so they are walked one level down.
         #
-        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter
+        # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook
         # @return [Array] every aggregate and entity
         def holders(bluebook)
           bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
@@ -31,11 +31,11 @@ module Hecks
         end
 
         # The last segment of a dotted name.
-        def bare(qualified) = qualified.to_s.split(".").last
+        def bare(qualified) = Naming.last_segment(qualified)
 
         # Gathers every term the glossary carries, ungrouped and unordered.
         #
-        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter
+        # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook
         # @param markings [Array<Hash{Symbol => String}>] sensitive fields to tag
         # @return [Array<Glossary::Entry>] every term
         def all(bluebook, markings = [])

data/lib/hecks/projections/glossary/html/page.rb

@@ -5,6 +5,9 @@ module Hecks
         # The page around the sections: the document shell, the navigation rail and the front
         # matter.
         module Page
+          # A `@@NAME@@` marker in `SHELL`, capturing the name.
+          MARKER = /@@(\w+)@@/
+
           # The document; `@@NAME@@` markers are filled in by `fill`.
           SHELL = <<~HTML.freeze
             <!doctype html>
@@ -66,7 +69,7 @@ module Hecks
           # Fills each `@@NAME@@` marker in one pass, so a value is never itself searched for
           # markers.
           def fill(template, values)
-            template.gsub(/@@(\w+)@@/) { values.fetch(Regexp.last_match(1)) }
+            template.gsub(MARKER) { values.fetch(Regexp.last_match(1)) }
           end
 
           def rail(title, sections, slugs)

data/lib/hecks/projections/glossary/html/parser.rb

@@ -4,6 +4,15 @@ module Hecks
       module Html
         # Reads the Markdown subset the glossary projector emits into `Html::Block`s.
         module Parser
+          # The line that opens a Mermaid code fence.
+          MERMAID_FENCE = /\A```mermaid/
+          # A heading line of level one to four: its hashes, then its text.
+          HEADING = /\A(\#{1,4}) (.+)\z/
+          # A block-quote line.
+          QUOTE = /\A> /
+          # A bulleted list item line.
+          LIST_ITEM = /\A- /
+
           module_function
 
           # Parses the Markdown subset the glossary projector emits into blocks.
@@ -24,10 +33,10 @@ module Hecks
             return [nil, index + 1] if line.strip.empty?
 
             case line
-            when /\A```mermaid/ then fence(lines, index)
-            when /\A(\#{1,4}) (.+)\z/ then [heading(Regexp.last_match), index + 1]
-            when /\A> / then [Block.new(type: :quote, text: line[2..]), index + 1]
-            when /\A- / then list(lines, index)
+            when MERMAID_FENCE then fence(lines, index)
+            when HEADING then [heading(Regexp.last_match), index + 1]
+            when QUOTE then [Block.new(type: :quote, text: line[2..]), index + 1]
+            when LIST_ITEM then list(lines, index)
             else paragraph(lines, index)
             end
           end

data/lib/hecks/projections/glossary/html/sections.rb

@@ -9,6 +9,9 @@ module Hecks
             "Always true:" => "rule", "Allowed only when:" => "rule", "Afterwards, always:" => "rule"
           }.freeze
 
+          # A paragraph that is all bold, `**Like this**`: the caption of the figure below it.
+          CAPTION = /\A\*\*[^*]+\*\*\z/
+
           module_function
 
           # GitHub's slugs for these headings, so links the Markdown carries land here too.
@@ -84,7 +87,7 @@ module Hecks
           end
 
           def paragraph(text, state)
-            if text.match?(/\A\*\*[^*]+\*\*\z/)
+            if text.match?(CAPTION)
               state[:caption] = text.delete("*")
             else
               klass = LEADS.find { |lead, _class| text.start_with?(lead) }&.last

data/lib/hecks/projections/glossary/html.rb

@@ -14,6 +14,13 @@ module Hecks
         FONTS   = "https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600;700&display=swap".freeze
         MERMAID = "https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js".freeze
 
+        # A Markdown in-page link: `[text](#anchor)`.
+        ANCHOR_LINK = /\[([^\]]+)\]\(#([^)]+)\)/
+        # Markdown bold text: `**text**`.
+        BOLD = /\*\*(.+?)\*\*/
+        # Markdown italic text: `*text*`.
+        ITALIC = /\*(.+?)\*/
+
         module_function
 
         # Renders `glossary.md`'s Markdown source as a self-contained HTML page.
@@ -38,9 +45,9 @@ module Hecks
         # Escapes first so prose never becomes a tag, then converts links, bold and italic.
         def inline(text)
           escape(text)
-            .gsub(/\[([^\]]+)\]\(#([^)]+)\)/) { %(<a href="##{Regexp.last_match(2)}">#{Regexp.last_match(1)}</a>) }
-            .gsub(/\*\*(.+?)\*\*/) { "<strong>#{Regexp.last_match(1)}</strong>" }
-            .gsub(/\*(.+?)\*/) { "<em>#{Regexp.last_match(1)}</em>" }
+            .gsub(ANCHOR_LINK) { %(<a href="##{Regexp.last_match(2)}">#{Regexp.last_match(1)}</a>) }
+            .gsub(BOLD) { "<strong>#{Regexp.last_match(1)}</strong>" }
+            .gsub(ITALIC) { "<em>#{Regexp.last_match(1)}</em>" }
         end
 
         def asset(name) = File.read(File.join(__dir__, name))

data/lib/hecks/projections/glossary/markdown.rb

@@ -24,7 +24,7 @@ module Hecks
 
         module_function
 
-        # Titles the document after its chapter.
+        # Titles the document after its bluebook.
         def title(bluebook) = "#{bluebook.name} glossary"
 
         # Renders the full `glossary.md` document.
@@ -58,8 +58,9 @@ module Hecks
         def section_opening(section, document)
           return ["> #{STANDING[section.name]}"] unless section.aggregate
 
-          marked = Sensitivity.for_aggregate(document.markings, document.bluebook.name, section.aggregate)
-          opening(section.aggregate, document.bluebook, marked)
+          bluebook = document.bluebook
+          marked = Sensitivity.for_aggregate(document.markings, bluebook.name, section.aggregate)
+          opening(section.aggregate, bluebook, marked)
         end
 
         # An aggregate's opening: what it is, how it fits and moves, what is always true.

data/lib/hecks/projections/glossary/mermaid.rb

@@ -6,9 +6,12 @@ module Hecks
       # The glossary's three diagrams: the map, one aggregate's context, and a lifecycle.
       # Value objects appear as words in the text, not as boxes, to keep diagrams small.
       module Mermaid
+        # A character a Mermaid node id may not hold.
+        NOT_ID_CHARACTER = /[^a-z0-9_]/
+
         module_function
 
-        # Draws the whole chapter's aggregates and which points at which.
+        # Draws the whole bluebook's aggregates and which points at which.
         #
         # @return [String] a Mermaid `flowchart LR` source
         def map(bluebook)
@@ -21,7 +24,7 @@ module Hecks
         # Adds a node for each reference target not yet drawn, and an edge for each reference.
         def add_references(lines, aggregate, names)
           references(aggregate).each do |attribute|
-            target = attribute.type.target_name
+            target = attribute.target_name
             lines << node(target) unless names.include?(target) || lines.include?(node(target))
             lines << edge(aggregate.hecks_name, attribute, target)
           end
@@ -43,7 +46,7 @@ module Hecks
         def neighbours(aggregate, bluebook)
           focus = aggregate.hecks_name
           entities(aggregate).flat_map { |attribute| link(focus, attribute, attribute.type.to_s) } +
-            references(aggregate).flat_map { |attribute| link(focus, attribute, attribute.type.target_name) } +
+            references(aggregate).flat_map { |attribute| link(focus, attribute, attribute.target_name) } +
             incoming(aggregate, bluebook)
         end
 
@@ -93,13 +96,13 @@ module Hecks
         # as `[holder, attribute]` pairs.
         def pointing_at(aggregate, bluebook)
           bluebook.aggregates.reject { |other| other.equal?(aggregate) }.flat_map do |other|
-            references(other).select { |attribute| attribute.type.target_name == aggregate.hecks_name }
+            references(other).select { |attribute| attribute.target_name == aggregate.hecks_name }
                              .map { |attribute| [other, attribute] }
           end
         end
 
         # A node id that carries no identifier: `n_atm_card`, never `n_ATMCard`.
-        def id(name) = "n_#{Naming.snake(name).gsub(/[^a-z0-9_]/, "_")}"
+        def id(name) = "n_#{Naming.snake(name).gsub(NOT_ID_CHARACTER, "_")}"
 
         # Renders one Mermaid node declaration, marked `focus` when asked.
         def node(name, focus: false)

data/lib/hecks/projections/glossary/sections.rb

@@ -7,7 +7,7 @@ module Hecks
       ROLES       = "Roles".freeze
       READ_MODELS = "Read models".freeze
       # Where a term lands when the fact it hangs on is raised by nothing
-      # this chapter declares — pizzas' `PizzaPaymentReceived` comes in
+      # this bluebook declares — pizzas' `PizzaPaymentReceived` comes in
       # through a port, so the policy reacting to it homes to no
       # aggregate. Shown, not dropped: a visible blank is how a reader
       # learns the language has a gap there.

data/lib/hecks/projections/glossary/sensitivity.rb

@@ -1,4 +1,5 @@
 require_relative "../../naming"
+require_relative "../plain_english"
 
 module Hecks
   module Projections
@@ -8,8 +9,8 @@ module Hecks
       module Sensitivity
         module_function
 
-        def for_aggregate(markings, chapter_name, aggregate)
-          qualified = "#{chapter_name}::#{aggregate.hecks_name}"
+        def for_aggregate(markings, declaration_name, aggregate)
+          qualified = "#{declaration_name}::#{aggregate.hecks_name}"
           markings.select { |marking| marking[:domain].to_s == qualified }
         end
 
@@ -31,9 +32,15 @@ module Hecks
 
         # Renders one "Handled as sensitive" line: field, category, and who may read it unredacted.
         def sentence(marking)
-          path = marking[:attribute_path].to_s.split(".").map { |part| Naming.words(part).downcase }.join(" ")
+          path = spoken_path(marking[:attribute_path])
           reader = Naming.words(marking[:readable_by]).downcase
-          "#{path.sub(/\A[[:lower:]]/, &:upcase)}: #{tag(marking)}, read unredacted only by the #{reader}."
+          "#{PlainEnglish.upper(path)}: #{tag(marking)}, read unredacted only by the #{reader}."
+        end
+
+        # A dotted field path as lowercase words: `card.daily_limit` -> "card daily limit".
+        def spoken_path(dotted)
+          parts = dotted.to_s.split(".")
+          parts.map { |part| Naming.words(part).downcase }.join(" ")
         end
       end
     end

data/lib/hecks/projections/glossary/sentences/actions.rb

@@ -15,6 +15,9 @@ module Hecks
             "delegate" => "passes on to", "corrects" => "corrects"
           }.freeze
 
+          # The `::` or `.` between the parts of a qualified event name.
+          NAME_SEPARATOR = /::|\./
+
           module_function
 
           # @param facts [Hash] the entry's facts: `:command`, `:holder` and `:value_objects`
@@ -57,7 +60,7 @@ module Hecks
 
           # "sets the name and the pizza"
           def change_phrase(verb, mutations)
-            fields = mutations.map { |mutation| "the #{PlainEnglish.noun(mutation.target.to_s.split(".").last)}" }
+            fields = mutations.map { |mutation| "the #{PlainEnglish.noun(Sentences.bare(mutation.target))}" }
             "#{verb} #{Naming.to_sentence_list(fields.uniq)}"
           end
 
@@ -78,7 +81,7 @@ module Hecks
 
           # "Records Topping added."
           def records(command, index)
-            events = command.emits.map { |event| index.link(:event, event.to_s.split(/::|\./).last) }
+            events = command.emits.map { |event| index.link(:event, event.to_s.split(NAME_SEPARATOR).last) }
             events.empty? ? nil : "Records #{Naming.to_sentence_list(events)}."
           end
         end

data/lib/hecks/projections/glossary/sentences/queries.rb

@@ -70,7 +70,8 @@ module Hecks
           end
 
           def nulls(query, things, label)
-            mode = query.null_semantics&.mode.to_s
+            null_semantics = query.null_semantics
+            mode = null_semantics&.mode.to_s
             return "" unless %w[first last].include?(mode)
 
             ", with #{things} that have no #{label} #{mode}"

data/lib/hecks/projections/glossary/sentences/value_objects.rb

@@ -19,7 +19,12 @@ module Hecks
           PATTERN_WORDS = {
             present: "must not be blank", not_empty: "must not be empty", no_whitespace: "must have no spaces",
             snake_name: "must be lowercase words joined by underscores", git_sha: "must be a commit id",
-            digits: "must be digits only"
+            digits: "must be digits only", identifier: "must start with a letter and use letters, digits and underscores",
+            csv_list: "must be a comma-separated list with no spaces", command_ref: "must name a command as Context::Aggregate.Command",
+            host_port: "must be a host name, optionally followed by a port", instance_id: "must be a server instance id",
+            hostname: "must be a host name", word_chars: "must use letters, digits and underscores only",
+            version: "must start with a version number such as 1.2.3", http_scheme: "must start with http:// or https://",
+            capitalized: "must contain a capitalized name", single_line: "must be one line"
           }.freeze
 
           module_function
@@ -31,7 +36,7 @@ module Hecks
 
           # A one-field object whose field is just "value" reads as its type ("Text.").
           def sentence(value_object, index, within, sensitive = {})
-            return closed_set_sentence(value_object.members) if value_object.closed_set?
+            return closed_set_sentence(value_object.members, index) if value_object.closed_set?
 
             attributes = value_object.attributes
             return "A marker with no details of its own." if attributes.empty?
@@ -61,7 +66,7 @@ module Hecks
           # A plain type in words, a reference as a link to what it points at, otherwise a link
           # to the value's own term.
           def type_words(field, index, within)
-            inner = if field.reference? then index.link(:aggregate, field.type.target_name)
+            inner = if field.reference? then index.link(:aggregate, field.target_name)
                     else TYPE_WORDS[field.type.to_s] || index.link(:value_object, field.type.to_s, within: within)
                     end
             field.list? ? "a list of #{inner}" : inner
@@ -76,15 +81,19 @@ module Hecks
           end
 
           # A multi-field row leads with its first field and keeps the rest beside it,
-          # so no row loses what makes it distinct.
-          def closed_set_sentence(members)
+          # so no row loses what makes it distinct. A member naming an aggregate (the variants
+          # of a `reference_to one_of`, ADR 0127) links to it.
+          def closed_set_sentence(members, index)
             if members.first && members.first.size > 1
               "One of: #{members.map { |row| row_phrase(row) }.join("; ")}."
             else
-              "One of #{Naming.to_sentence_list(members.flat_map(&:values).uniq.map(&:to_s), conj: "or")}."
+              values = members.flat_map(&:values).uniq.map { |value| member_words(value.to_s, index) }
+              "One of #{Naming.to_sentence_list(values, conj: "or")}."
             end
           end
 
+          def member_words(value, index) = index[:aggregate, value] ? index.link(:aggregate, value) : value
+
           def row_phrase(row)
             lead, *rest = row.map { |field, value| [field, value] }
             "#{lead.last} (#{rest.map { |field, value| "#{Naming.words(field).downcase} #{value}" }.join(", ")})"

data/lib/hecks/projections/glossary/sentences.rb

@@ -21,6 +21,9 @@ module Hecks
           read_model: ->(facts, _index) { facts[:read_model].description }
         }.freeze
 
+        # The capital letter a text opens with.
+        LEADING_UPPER = /\A[[:upper:]]/
+
         module_function
 
         def paragraphs(entry, index)
@@ -132,13 +135,13 @@ module Hecks
           [holder, command]
         end
 
-        def bare(qualified) = qualified.to_s.split(".").last
+        def bare(qualified) = Naming.last_segment(qualified)
 
         def with_period(text) = text.to_s.strip.end_with?(".", "!", "?") ? text.to_s.strip : "#{text.to_s.strip}."
 
-        def lower_first(text) = text.sub(/\A[[:upper:]]/, &:downcase)
+        def lower_first(text) = text.sub(LEADING_UPPER, &:downcase)
 
-        def upper_first(text) = text.sub(/\A[[:lower:]]/, &:upcase)
+        def upper_first(text) = PlainEnglish.upper(text)
       end
     end
   end