hecks 3.4.2 → 3.6.0

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

@@ -0,0 +1,140 @@
+module Hecks
+  module Projections
+    module Glossary
+      # Gathers every term a chapter'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
+        # @return [Array] every aggregate and entity
+        def holders(bluebook)
+          bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
+        end
+
+        # Maps every holder name to its owning aggregate's name.
+        def holder_aggregate(bluebook)
+          bluebook.aggregates.each_with_object({}) do |aggregate, map|
+            map[aggregate.hecks_name] = aggregate.hecks_name
+            aggregate.entities.each { |entity| map[entity.hecks_name] = aggregate.hecks_name }
+          end
+        end
+
+        # Maps each emitted event to its `[holder, command]` raisers. An event is never
+        # declared, so its home is the first raiser's aggregate.
+        def event_raisers(bluebook)
+          holders(bluebook).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |holder, map|
+            holder.commands.each { |command| command.emits.each { |event| map[event] << [holder, command] } }
+          end
+        end
+
+        # The last segment of a dotted name.
+        def bare(qualified) = qualified.to_s.split(".").last
+
+        # Gathers every term the glossary carries, ungrouped and unordered.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter
+        # @param markings [Array<Hash{Symbol => String}>] sensitive fields to tag
+        # @return [Array<Glossary::Entry>] every term
+        def all(bluebook, markings = [])
+          homes = holder_aggregate(bluebook)
+
+          entity_entries(bluebook) + value_object_entries(bluebook, markings) + verb_entries(bluebook, homes) +
+            reaction_entries(bluebook, homes) + role_entries(bluebook) + read_model_entries(bluebook)
+        end
+
+        # The events, the policies that react to them and the sagas they start, each homed with
+        # the aggregate of its event's first raiser.
+        def reaction_entries(bluebook, homes)
+          raisers = event_raisers(bluebook)
+          home_of = ->(event) { raisers.key?(event) ? homes[raisers[event].first.first.hecks_name] : nil }
+          event_entries(bluebook, raisers, home_of) + policy_entries(bluebook, home_of) +
+            saga_entries(bluebook, home_of)
+        end
+
+        def entity_entries(bluebook)
+          bluebook.aggregates.flat_map do |aggregate|
+            aggregate.entities.map do |entity|
+              Entry.new(name: entity.hecks_name, kind: :entity, within: aggregate.hecks_name,
+                        section: aggregate.hecks_name, facts: { entity: entity })
+            end
+          end
+        end
+
+        # Aggregates only; `Bluebook::Entity` deliberately does not answer `value_objects`.
+        def value_object_entries(bluebook, markings = [])
+          bluebook.aggregates.flat_map do |aggregate|
+            marked = Sensitivity.for_aggregate(markings, bluebook.name, aggregate)
+            aggregate.value_objects.map do |value_object|
+              sensitive = Sensitivity.for_value_object(marked, aggregate, value_object)
+              Entry.new(name: value_object.hecks_name, kind: :value_object, within: aggregate.hecks_name,
+                        section: aggregate.hecks_name,
+                        facts: { value_object: value_object, sensitive: sensitive })
+            end
+          end
+        end
+
+        def verb_entries(bluebook, homes)
+          holders(bluebook).flat_map { |holder| command_entries(holder, homes) + query_entries(holder, homes) }
+        end
+
+        def command_entries(holder, homes)
+          holder.commands.map do |command|
+            Entry.new(name: command.hecks_name, kind: :command, within: holder.hecks_name,
+                      section: homes[holder.hecks_name], facts: { command: command, holder: holder })
+          end
+        end
+
+        def query_entries(holder, homes)
+          holder.queries.map do |query|
+            Entry.new(name: query.hecks_name, kind: :query, within: holder.hecks_name,
+                      section: homes[holder.hecks_name], facts: { query: query })
+          end
+        end
+
+        def event_entries(bluebook, raisers, home_of)
+          raisers.map do |event, raised_by|
+            reactions = bluebook.policies.select { |policy| bare(policy.on_event) == event }
+            Entry.new(name: event, kind: :event, section: home_of.call(event),
+                      facts: { event: event, raised_by: raised_by, policies: reactions })
+          end
+        end
+
+        def policy_entries(bluebook, home_of)
+          bluebook.policies.map do |policy|
+            Entry.new(name: policy.name, kind: :policy, section: home_of.call(bare(policy.on_event)),
+                      facts: { policy: policy })
+          end
+        end
+
+        def saga_entries(bluebook, home_of)
+          bluebook.process_managers.map do |saga|
+            shape = saga.to_h
+            Entry.new(name: shape[:name], kind: :saga, section: home_of.call(bare(shape[:starts_on])),
+                      facts: { saga: shape })
+          end
+        end
+
+        # Roles cut across aggregates, so they get their own section.
+        def role_entries(bluebook)
+          by_role = Hash.new { |hash, key| hash[key] = [] }
+          holders(bluebook).each do |holder|
+            holder.commands.select(&:role).each { |command| by_role[command.role] << [holder, command] }
+          end
+          by_role.map do |role, issues|
+            Entry.new(name: role, kind: :role, section: ROLES, facts: { role: role, commands: issues })
+          end
+        end
+
+        # A read model joins heads from more than one aggregate, so it belongs to none.
+        def read_model_entries(bluebook)
+          bluebook.read_models.map do |read_model|
+            Entry.new(name: read_model.name, kind: :read_model, section: READ_MODELS, facts: { read_model: read_model })
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+module Hecks
+  module Projections
+    module Glossary
+      module Html
+        # The page around the sections: the document shell, the navigation rail and the front
+        # matter.
+        module Page
+          # The document; `@@NAME@@` markers are filled in by `fill`.
+          SHELL = <<~HTML.freeze
+            <!doctype html>
+            <html lang="en">
+            <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>@@TITLE@@</title>
+            <link rel="stylesheet" href="@@FONTS@@">
+            <script src="@@MERMAID@@"></script>
+            <style>
+            @@CSS@@
+            </style>
+            </head>
+            <body>
+            <div class="page">
+            @@RAIL@@
+            <main>
+            @@FRONT@@
+            @@SECTIONS@@
+            </main>
+            </div>
+            <script>
+            @@JS@@
+            </script>
+            </body>
+            </html>
+          HTML
+
+          # The navigation rail; `@@NAME@@` markers are filled in by `fill`.
+          RAIL = <<~HTML.freeze
+            <nav class="rail" aria-label="Sections">
+            <p class="domain">@@DOMAIN@@</p>
+            <p class="sub">Glossary</p>
+            <input type="search" placeholder="Find a term" aria-label="Find a term" autocomplete="off">
+            <p class="count"></p>
+            <ol>
+            @@ITEMS@@
+            </ol>
+            </nav>
+          HTML
+
+          module_function
+
+          # @param title [String] the document's title
+          # @param sections [Array<Hash>] the front matter, then each section
+          # @param slugs [Hash] each heading's slug
+          # @return [String] the whole page
+          def page(title, sections, slugs)
+            front, *rest = sections
+            fill(SHELL, "TITLE" => Html.escape(title), "FONTS" => Html::FONTS, "MERMAID" => Html::MERMAID,
+                        "CSS" => Html.asset("page.css"), "RAIL" => rail(title, rest, slugs),
+                        "FRONT" => front_matter(front[:blocks]),
+                        "SECTIONS" => rest.map { |section| Sections.section_html(section, slugs) }.join("\n"),
+                        "JS" => Html.asset("page.js"))
+          end
+
+          # 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)) }
+          end
+
+          def rail(title, sections, slugs)
+            domain = title.split(" — ").first
+            items = sections.map do |section|
+              heading = section[:heading]
+              %(<li><a href="##{slugs[heading]}">#{Html.inline(heading.text)}</a></li>)
+            end
+            fill(RAIL, "DOMAIN" => Html.escape(domain), "ITEMS" => items.join("\n"))
+          end
+
+          def front_matter(blocks)
+            ["<header>", *blocks.filter_map { |block| front_part(block) }, "</header>"].join("\n")
+          end
+
+          def front_part(block)
+            case block.type
+            when :heading   then "<h1>#{Html.inline(block.text.split(" — ").first)}</h1>"
+            when :quote     then "<p class=\"vision\">#{Html.inline(block.text)}</p>"
+            when :paragraph then "<p class=\"lede\">#{Html.inline(block.text)}</p>"
+            when :mermaid   then Html.figure(block, "How it all fits together")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+module Hecks
+  module Projections
+    module Glossary
+      module Html
+        # Reads the Markdown subset the glossary projector emits into `Html::Block`s.
+        module Parser
+          module_function
+
+          # Parses the Markdown subset the glossary projector emits into blocks.
+          def parse(markdown)
+            lines  = markdown.lines.map(&:chomp)
+            blocks = []
+            index  = 0
+            while index < lines.size
+              block, index = read_block(lines, index)
+              blocks << block if block
+            end
+            blocks
+          end
+
+          # The block that starts at `index` (nil for a blank line), and the index just past it.
+          def read_block(lines, index)
+            line = lines[index]
+            return [nil, index + 1] if line.strip.empty?
+
+            case line
+            when /\A```mermaid/ then fence(lines, index)
+            when /\A(\#{1,3}) (.+)\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)
+            else paragraph(lines, index)
+            end
+          end
+
+          def heading(match) = Block.new(type: :heading, text: match[2], level: match[1].size)
+
+          def list(lines, index)
+            items, index = run(lines, index) { |text| text.start_with?("- ") }
+            [Block.new(type: :list, items: items.map { |item| item[2..] }), index]
+          end
+
+          def paragraph(lines, index)
+            para, index = run(lines, index) { |text| !text.strip.empty? }
+            [Block.new(type: :paragraph, text: para.join(" ")), index]
+          end
+
+          # The mermaid block opened at `index`, and the line index just past its closing fence.
+          def fence(lines, index)
+            close = ((index + 1)...lines.size).find { |at| lines[at] == "```" } || lines.size
+            [Block.new(type: :mermaid, text: lines[(index + 1)...close].join("\n")), close + 1]
+          end
+
+          # The consecutive lines from `index` that satisfy the block, and the index past them.
+          def run(lines, index)
+            taken = []
+            while index < lines.size && yield(lines[index])
+              taken << lines[index]
+              index += 1
+            end
+            [taken, index]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+module Hecks
+  module Projections
+    module Glossary
+      module Html
+        # Groups parsed blocks into the page's sections and renders each section's terms.
+        module Sections
+          module_function
+
+          # GitHub's slugs for these headings, so links the Markdown carries land here too.
+          # Keyed by identity: a Struct compares by members, so two "### Open" headings in
+          # different sections would collide and `#open` would have nothing to land on.
+          def heading_slugs(blocks)
+            take  = Slugs.slug_taker
+            slugs = {}.compare_by_identity
+            blocks.select { |block| block.type == :heading }.each { |block| slugs[block] = take.call(block.text) }
+            slugs
+          end
+
+          # Blocks before the first `##` are front matter (heading nil); each `##` opens a section.
+          def split_sections(blocks)
+            sections = [{ heading: nil, blocks: [] }]
+            blocks.each do |block|
+              sections << { heading: block, blocks: [] } if block.type == :heading && block.level == 2
+              sections.last[:blocks] << block
+            end
+            sections
+          end
+
+          # Each `###` opens an article running to the next. A bold-only paragraph
+          # captions whatever figure or list follows it.
+          def section_html(section, slugs)
+            heading = section[:heading]
+            state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{Html.inline(heading.text)}</h2>"],
+                      caption: nil, in_terms: false }
+            section[:blocks].drop(1).each { |block| section_block(block, state, slugs) }
+            state[:parts] << "</article></div>" if state[:in_terms]
+            state[:parts] << "</section>"
+            state[:parts].join("\n")
+          end
+
+          # Renders one block into `state[:parts]`, mutating `state`.
+          def section_block(block, state, slugs)
+            case block.type
+            when :heading then open_term(block, state, slugs)
+            when :mermaid then state[:parts] << Html.figure(block, state.delete(:caption))
+            when :list then list(block, state)
+            when :quote then state[:parts] << "<p class=\"about\">#{Html.inline(block.text)}</p>"
+            when :paragraph then paragraph(block.text, state)
+            end
+          end
+
+          def open_term(block, state, slugs)
+            parts = state[:parts]
+            parts << (state[:in_terms] ? "</article>" : "<div class=\"terms\">")
+            parts << %(<article class="term" id="#{slugs[block]}">) << "<h3>#{Html.inline(block.text)}</h3>"
+            state[:in_terms] = true
+          end
+
+          def list(block, state)
+            caption = state.delete(:caption)
+            state[:parts] << "<p class=\"caption\">#{Html.escape(caption)}</p>" if caption
+            items = block.items.map { |item| "<li>#{Html.inline(item)}</li>" }.join
+            state[:parts] << "<ul class=\"rules\">#{items}</ul>"
+          end
+
+          def paragraph(text, state)
+            if text.match?(/\A\*\*[^*]+\*\*\z/)
+              state[:caption] = text.delete("*")
+            else
+              klass = text.start_with?("Always true:") ? " class=\"rule\"" : ""
+              state[:parts] << "<p#{klass}>#{Html.inline(text)}</p>"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,7 @@
 require_relative "../../forms/html"
+require_relative "html/parser"
+require_relative "html/sections"
+require_relative "html/page"
 
 module Hecks
   module Projections
@@ -17,186 +20,11 @@ module Hecks
         # Renders `glossary.md`'s Markdown source as a self-contained HTML page.
         # Reads only the Markdown, never the bluebook, so the two cannot drift.
         def render(markdown)
-          blocks = parse(markdown)
-          slugs  = heading_slugs(blocks)
+          blocks = Parser.parse(markdown)
+          slugs  = Sections.heading_slugs(blocks)
           title  = blocks.find { |block| block.type == :heading && block.level == 1 }&.text.to_s
-          sections = split_sections(blocks)
-          page(title, sections, slugs)
-        end
-
-        # Parses the Markdown subset the glossary projector emits into blocks.
-        def parse(markdown)
-          lines  = markdown.lines.map(&:chomp)
-          blocks = []
-          index  = 0
-          while index < lines.size
-            line = lines[index]
-            if line.start_with?("```mermaid")
-              block, index = fence(lines, index)
-              blocks << block
-            elsif (heading = line.match(/\A(\#{1,3}) (.+)\z/))
-              blocks << Block.new(type: :heading, text: heading[2], level: heading[1].size)
-              index += 1
-            elsif line.start_with?("> ")
-              blocks << Block.new(type: :quote, text: line[2..])
-              index += 1
-            elsif line.start_with?("- ")
-              items, index = run(lines, index) { |text| text.start_with?("- ") }
-              blocks << Block.new(type: :list, items: items.map { |item| item[2..] })
-            elsif line.strip.empty?
-              index += 1
-            else
-              para, index = run(lines, index) { |text| !text.strip.empty? }
-              blocks << Block.new(type: :paragraph, text: para.join(" "))
-            end
-          end
-          blocks
-        end
-
-        # The mermaid block opened at `index`, and the line index just past its closing fence.
-        def fence(lines, index)
-          close = ((index + 1)...lines.size).find { |at| lines[at] == "```" } || lines.size
-          [Block.new(type: :mermaid, text: lines[(index + 1)...close].join("\n")), close + 1]
-        end
-
-        # The consecutive lines from `index` that satisfy the block, and the index past them.
-        def run(lines, index)
-          taken = []
-          while index < lines.size && yield(lines[index])
-            taken << lines[index]
-            index += 1
-          end
-          [taken, index]
-        end
-
-        # GitHub's slugs for these headings, so links the Markdown carries land here too.
-        # Keyed by identity: a Struct compares by members, so two "### Open" headings in
-        # different sections would collide and `#open` would have nothing to land on.
-        def heading_slugs(blocks)
-          seen  = Hash.new(0)
-          slugs = {}.compare_by_identity
-          blocks.select { |block| block.type == :heading }.each do |block|
-            base = Slugs.github(block.text)
-            seen[base] += 1
-            slugs[block] = seen[base] == 1 ? base : "#{base}-#{seen[base] - 1}"
-          end
-          slugs
-        end
-
-        # Blocks before the first `##` are front matter (heading nil); each `##` opens a section.
-        def split_sections(blocks)
-          sections = [{ heading: nil, blocks: [] }]
-          blocks.each do |block|
-            sections << { heading: block, blocks: [] } if block.type == :heading && block.level == 2
-            sections.last[:blocks] << block
-          end
-          sections
-        end
-
-        def page(title, sections, slugs)
-          front, *rest = sections
-          <<~HTML
-            <!doctype html>
-            <html lang="en">
-            <head>
-            <meta charset="utf-8">
-            <meta name="viewport" content="width=device-width, initial-scale=1">
-            <title>#{escape(title)}</title>
-            <link rel="stylesheet" href="#{FONTS}">
-            <script src="#{MERMAID}"></script>
-            <style>
-            #{asset('page.css')}
-            </style>
-            </head>
-            <body>
-            <div class="page">
-            #{rail(title, rest, slugs)}
-            <main>
-            #{front_matter(front[:blocks])}
-            #{rest.map { |section| section_html(section, slugs) }.join("\n")}
-            </main>
-            </div>
-            <script>
-            #{asset('page.js')}
-            </script>
-            </body>
-            </html>
-          HTML
-        end
-
-        def rail(title, sections, slugs)
-          domain = title.split(" — ").first
-          items = sections.map do |section|
-            heading = section[:heading]
-            %(<li><a href="##{slugs[heading]}">#{inline(heading.text)}</a></li>)
-          end
-          <<~HTML
-            <nav class="rail" aria-label="Sections">
-            <p class="domain">#{escape(domain)}</p>
-            <p class="sub">Glossary</p>
-            <input type="search" placeholder="Find a term" aria-label="Find a term" autocomplete="off">
-            <p class="count"></p>
-            <ol>
-            #{items.join("\n")}
-            </ol>
-            </nav>
-          HTML
-        end
-
-        def front_matter(blocks)
-          parts = ["<header>"]
-          blocks.each do |block|
-            case block.type
-            when :heading   then parts << "<h1>#{inline(block.text.split(' — ').first)}</h1>"
-            when :quote     then parts << "<p class=\"vision\">#{inline(block.text)}</p>"
-            when :paragraph then parts << "<p class=\"lede\">#{inline(block.text)}</p>"
-            when :mermaid   then parts << figure(block, "How it all fits together")
-            end
-          end
-          parts << "</header>"
-          parts.join("\n")
-        end
-
-        # Each `###` opens an article running to the next. A bold-only paragraph
-        # captions whatever figure or list follows it.
-        def section_html(section, slugs)
-          heading = section[:heading]
-          state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{inline(heading.text)}</h2>"],
-                    caption: nil, in_terms: false }
-          section[:blocks].drop(1).each { |block| section_block(block, state, slugs) }
-          state[:parts] << "</article></div>" if state[:in_terms]
-          state[:parts] << "</section>"
-          state[:parts].join("\n")
-        end
-
-        # Renders one block into `state[:parts]`, mutating `state`.
-        def section_block(block, state, slugs)
-          parts = state[:parts]
-          case block.type
-          when :heading
-            parts << (state[:in_terms] ? "</article>" : "<div class=\"terms\">")
-            parts << %(<article class="term" id="#{slugs[block]}">) << "<h3>#{inline(block.text)}</h3>"
-            state[:in_terms] = true
-          when :mermaid
-            parts << figure(block, state.delete(:caption))
-          when :list
-            caption = state.delete(:caption)
-            parts << "<p class=\"caption\">#{escape(caption)}</p>" if caption
-            parts << "<ul class=\"rules\">#{block.items.map { |item| "<li>#{inline(item)}</li>" }.join}</ul>"
-          when :quote
-            parts << "<p class=\"about\">#{inline(block.text)}</p>"
-          when :paragraph
-            paragraph(block.text, state)
-          end
-        end
-
-        def paragraph(text, state)
-          if text.match?(/\A\*\*[^*]+\*\*\z/)
-            state[:caption] = text.delete("*")
-          else
-            klass = text.start_with?("Always true:") ? " class=\"rule\"" : ""
-            state[:parts] << "<p#{klass}>#{inline(text)}</p>"
-          end
+          sections = Sections.split_sections(blocks)
+          Page.page(title, sections, slugs)
         end
 
         def figure(block, caption)

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

@@ -0,0 +1,45 @@
+require_relative "../../naming"
+
+module Hecks
+  module Projections
+    module Glossary
+      # Resolves declared references structurally, never by searching prose. An
+      # undeclared target (a cross-domain command) answers nil and renders unlinked.
+      class Index
+        def initialize(sections)
+          @by_key = {}
+          sections.each do |section|
+            @by_key[[:aggregate, section.name]] = section if section.aggregate
+            section.terms.each { |entry| @by_key[key_of(entry)] = entry }
+          end
+        end
+
+        # Commands, queries and value objects can share a bare name across holders, so
+        # their key includes the holder.
+        def key_of(entry)
+          case entry.kind
+          when :command, :query, :value_object then [entry.kind, entry.within, entry.name]
+          else [entry.kind, entry.name]
+          end
+        end
+
+        # Looks up a term or aggregate section by kind and name.
+        #
+        # @return [Entry, Section, nil]
+        def [](kind, name, within: nil)
+          @by_key[within ? [kind, within, name] : [kind, name]]
+        end
+
+        # A Markdown link to a term's heading, or the plain words when undeclared.
+        # `label:` overrides the link text to tell two same-named terms apart.
+        def link(kind, name, within: nil, label: nil)
+          target = self[kind, name, within: within]
+          return label || Naming.words(name) unless target
+
+          text = label || (target.is_a?(Section) ? target.title : target.headword)
+          "[#{text}](##{target.slug})"
+        end
+      end
+    end
+  end
+end

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

@@ -47,15 +47,16 @@ module Hecks
 
         # Renders one `##` section: its opening, then every term inside it.
         def section_text(section, document)
-          parts = ["## #{section.title}"]
-          parts += if section.aggregate
-                     marked = Sensitivity.for_aggregate(document.markings, document.bluebook.name, section.aggregate)
-                     opening(section.aggregate, document.bluebook, marked)
-                   else
-                     ["> #{STANDING[section.name]}"]
-                   end
-          parts += section.terms.map { |entry| term_text(entry, document.index) }
-          parts.join("\n\n")
+          terms = section.terms.map { |entry| term_text(entry, document.index) }
+          ["## #{section.title}", *section_opening(section, document), *terms].join("\n\n")
+        end
+
+        # The paragraphs that open a section: an aggregate's own, or the standing note of a group.
+        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)
         end
 
         # An aggregate's opening: what it is, how it fits and moves, what is always true.
@@ -63,9 +64,19 @@ module Hecks
           parts = []
           parts << "> #{aggregate.description}" if aggregate.description
           parts << Sentences.lifecycle_sentence(aggregate.lifecycle) if aggregate.lifecycle
-          parts << "**How it fits**" << fence(Mermaid.context(aggregate, bluebook))
+          parts + diagrams(aggregate, bluebook) + facts(always_true(aggregate, bluebook), marked)
+        end
+
+        # The "How it fits" diagram, and "How it moves" when the aggregate has a lifecycle.
+        def diagrams(aggregate, bluebook)
+          parts = ["**How it fits**", fence(Mermaid.context(aggregate, bluebook))]
           parts << "**How it moves**" << fence(Mermaid.lifecycle(aggregate)) if aggregate.lifecycle
-          statements = always_true(aggregate, bluebook)
+          parts
+        end
+
+        # The "Always true" and "Handled as sensitive" lists, each only when it has lines.
+        def facts(statements, marked)
+          parts = []
           parts << "**Always true**" << statements.map { |statement| "- #{statement}" }.join("\n") unless statements.empty?
           unless marked.empty?
             lines = marked.map { |marking| "- #{Sensitivity.sentence(marking)}" }