hecks 3.10.0 → 3.11.0

data/lib/hecks/projections/deploy/box/templates/deploy-box.sh.tmpl

@@ -8,6 +8,14 @@
 #   40  the box stack has no instance
 #   41  the roll did not succeed on the box
 #   42  the roll succeeded but the box is not healthy after it
+#   43  no restore anchor: the database's backups cannot be read, or are kept fewer days than
+#       MIN_BACKUP_RETENTION_DAYS (default 3)
+#
+# Before anything changes, the roll names the point the database can be restored to: the instance, the
+# moment this roll starts, and how long its continuous backups are kept. A roll that mints a new era is
+# a one-way door, so this is the rollback anchor, and it costs nothing (a point-in-time restore uses the
+# backups the instance already keeps, where a manual snapshot would be stored until someone deleted it).
+# SKIP_RESTORE_ANCHOR=1 skips it.
 #
 # Before the roll replaces a container, the box saves that container's log to
 # /var/log/hecks-captures/<container>-<UTC timestamp>.log and keeps the newest 14 per container
@@ -30,6 +38,27 @@ DB_HOST=$(out "$RDS_STACK" DbEndpoint)
 [ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 40; }
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
 
+if [ "${SKIP_RESTORE_ANCHOR:-}" = 1 ]; then
+  echo "==> skipping the restore anchor (SKIP_RESTORE_ANCHOR=1)"
+else
+  DB_ID=${DB_HOST%%.*}
+  BACKUPS=$(aws rds describe-db-instances --db-instance-identifier "$DB_ID" \
+    --query 'DBInstances[0].[BackupRetentionPeriod,LatestRestorableTime]' --output text) || BACKUPS=
+  read -r KEPT_DAYS RESTORABLE <<< "$BACKUPS"
+  case "${KEPT_DAYS:-}" in ''|*[!0-9]*)
+    echo "==> no restore anchor: could not read the backups of $DB_ID (SKIP_RESTORE_ANCHOR=1 rolls without one)" >&2
+    exit 43 ;;
+  esac
+  if [ "$KEPT_DAYS" -lt "${MIN_BACKUP_RETENTION_DAYS:-3}" ]; then
+    echo "==> no restore anchor: $DB_ID keeps backups $KEPT_DAYS day(s), fewer than ${MIN_BACKUP_RETENTION_DAYS:-3}" >&2
+    exit 43
+  fi
+  ANCHOR_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  echo "==> restore anchor: $DB_ID restorable to $ANCHOR_AT (latest $RESTORABLE, backups kept $KEPT_DAYS days)"
+  echo "    to return: aws rds restore-db-instance-to-point-in-time --source-db-instance-identifier $DB_ID \\"
+  echo "      --target-db-instance-identifier $DB_ID-restore --restore-time $ANCHOR_AT"
+fi
+
 WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
 
 # SMOKE_LISTENER=1 (a rehearsal box only) mounts a loopback HTTPS site on 127.0.0.1:8443 that adds the

data/lib/hecks/projections/deploy/box/templates/deploy-service.sh.tmpl

@@ -24,7 +24,7 @@
 #   32  the box's Compose file is unreadable    33  the box stack has no instance
 #   34  the stack has no parameter for the container   35  the stack update failed or did not settle
 #   36  a parameter other than the container's changed  37  the task definition lacks the pushed image
-#   38  the task definition has no such container      40-42  deploy-box.sh's own
+#   38  the task definition has no such container      40-43  deploy-box.sh's own
 #
 # Environment:
 #   LOCAL_IMAGE               local image to push, default <ecr repository>:latest

data/lib/hecks/projections/deploy/preview/preview.sh.erb

@@ -365,7 +365,7 @@ signup_admin() {
 # Prints what to paste into the browser console to sign in as the preview's first
 # admin: a session for that email signed with THIS preview's session secret (the
 # secret itself is never printed). Anyone with AWS access to the account could
-# mint the same, which is the point: it is the deployer's door, not a public one.
+# mint the same, which is the point: it is the deployer's entry, not a public one.
 cmd_login() {
   [ -n "$(stack_status)" ] || die "no preview for branch '$BRANCH' - run 'preview.sh deploy'"
   admin_identity

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

@@ -7,6 +7,9 @@ module Hecks
       # VPC, RDS/Aurora, bastion and cross-domain invoke plumbing shared by the
       # `Lambda` and `Fargate` deploy targets. Plain module functions, not a Target.
       module Shared
+        # Raised when a bastion parameter names a stack output that is not declared.
+        class Error < RuntimeError; end
+
         # The names a domain's own VPC and database are rendered by.
         #
         # @!attribute [r] shared [Boolean] whether this domain borrows another domain's RDS instance
@@ -66,11 +69,11 @@ module Hecks
 
         # Generation-time check that every bastion parameter maps to a stack output.
         #
-        # @raise [RuntimeError] if a parameter names a `from_output` absent from `stack_outputs`
+        # @raise [Error] if a parameter names a `from_output` absent from `stack_outputs`
         def check_bastion_parameters!(bastion_parameters, stack_outputs)
           bastion_parameters.each do |param|
             stack_outputs.any? { |o| o[:key] == param[:from_output] } or
-              raise "bastion parameter #{param[:name]} references undeclared stack output #{param[:from_output]}"
+              raise Error, "bastion parameter #{param[:name]} references undeclared stack output #{param[:from_output]}"
           end
         end
 

data/lib/hecks/projections/model/deviations.rb

@@ -17,8 +17,8 @@ module Hecks
 
         # One model field gathered from several declared ones.
         FOLDED = {
-          "Aggregate" => { lifecycle: %i[state_field state_start transitions] },
-          "Entity"    => { lifecycle: %i[state_field state_start transitions] },
+          "Aggregate" => { lifecycle: %i[state_field state_start transitions marks] },
+          "Entity"    => { lifecycle: %i[state_field state_start transitions marks] },
           "Query"     => { order_by: %i[order_field order_way] }
         }.freeze
 

data/lib/hecks/projections/model.rb

@@ -16,10 +16,10 @@ module Hecks
           construct: "Policy",
           file:      "policy.rb",
           behaviour: "Behaviour::Policy",
-          readers:   %i[name on_event trigger_command target_domain expect_undelivered where for_each with_spec],
+          readers:   %i[name on_event trigger_command ask target_domain expect_undelivered where for_each with_spec],
           accessors: %i[aggregate],
           defaults:  { name: nil, on_event: "nil", trigger_command: "nil",
-                       target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
+                       ask: "nil", target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
                        with_spec: "[]", aggregate: "nil" },
           # The language holds a flag as "true" and the builder as `true`; both become a boolean.
           coerce:    { name: ".to_s", aggregate: "&.to_s", expect_undelivered: ".to_s == \"true\"" },

data/lib/hecks/projections/oidc.rb

@@ -1,3 +1,4 @@
+require "json"
 require_relative "../naming"
 require_relative "../projector"
 
@@ -35,6 +36,17 @@ module Hecks
         }
       end
 
+      # The manifest as the text `oidc.json` holds: indented JSON ending in a newline, with an empty
+      # list as `[]`. `JSON.pretty_generate` spells an empty list `[\n\n]` in some json releases
+      # (2.7.2 among them) and `[]` in others, so the file is normalised here and a committed
+      # manifest compares equal whichever json a machine has.
+      #
+      # @param manifest [Hash{String => Object}] what `call` returns
+      # @return [String] the text of the manifest file
+      def render(manifest)
+        "#{JSON.pretty_generate(manifest).gsub(/\[\n\s*\]/, "[]")}\n"
+      end
+
       # Every command's scope entry, entity commands included (they dispatch as `Entity.Command`).
       # Sorted by scope so two manifest versions diff cleanly.
       #
@@ -79,7 +91,7 @@ module Hecks
       end
 
       # One scope entry per command, spelled like `banking:account.open`; snake-cased through
-      # `Naming.snake`, as the facade names its door methods.
+      # `Naming.snake`, as the facade names its module methods.
       #
       # @param commands [Array<Bluebook::Command>] the commands to project
       # @param verb_prefix [String] the owning aggregate or entity's fully-qualified

data/lib/hecks/projections/shape.rb

@@ -6,6 +6,9 @@ module Hecks
     # The storage shape of one bluebook, the form `StorageShape.mint_hash` hashes to name an era.
     # Diffing two of these answers whether a change bumps the era.
     module Shape
+      # Raised when the shape projection is asked for without the era plugin loaded.
+      class Error < RuntimeError; end
+
       extend Projector::Target
 
       projects_as :shape
@@ -15,8 +18,8 @@ module Hecks
       # Registered even when the era plugin is unloaded; the call then refuses clearly.
       def call(bluebook:, options: {})
         unless Ports::Persistence.plugin?(:era)
-          raise "the :shape projection needs the era persistence plugin loaded " \
-                "(require \"hecks/ports/persistence/plugins/era\")"
+          raise Error, "the :shape projection needs the era persistence plugin loaded " \
+                       "(require \"hecks/ports/persistence/plugins/era\")"
         end
 
         Runtime::StorageShape.project(bluebook)

data/lib/hecks/projections/site/cms_editor/attributes.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "blocks"
+require_relative "hints"
+
 module Hecks
   module Projections
     module Site
@@ -9,11 +12,8 @@ module Hecks
         #
         # A type that names one of the aggregate's value objects is an `object`; a reference is a
         # `reference`; the primitives are `integer`, `number`, `boolean` and `text`, and any other
-        # name is entered as text.
-        #
-        # An attribute whose value object has the shape of a structured document, a `blocks`
-        # list of a value object that has `kind` and `spans`, carries `widget: "body"` and is
-        # edited with the rich-text widget. The shape decides it, never a name.
+        # is text. The shape decides what more it is, never a name: a body (`widget: "body"`), a
+        # block list (see `Blocks`), a moment, a `<kind>:` key (see `Hints`) or a picture.
         class Attributes
           # The parts a value object needs for its list of blocks to be a document body's blocks.
           BLOCK_PARTS = %w[kind spans].freeze
@@ -26,6 +26,7 @@ module Hecks
           def initialize(objects)
             @by_name = objects.to_h { |object| [object.hecks_name, object] }
             @objects = @by_name.keys
+            @hints = Hints.new(@by_name)
           end
 
           # @param attribute [Bluebook::Attribute] a declared attribute
@@ -35,11 +36,30 @@ module Hecks
             return reference(attribute, type.target_name) if type.is_a?(Bluebook::Reference)
 
             entry = base(attribute, type.to_s, kind(type.to_s))
-            body?(attribute) ? entry.merge("widget" => "body") : entry
+            return entry.merge("widget" => "body") if body?(attribute)
+
+            entry.merge(@hints.of(attribute), listing(attribute), pictured(attribute))
           end
 
           private
 
+          # @return [Hash{String => Object}] `blockList` when the attribute is a list of blocks
+          def listing(attribute)
+            found = Blocks.of(attribute, @by_name)
+            found ? { "blockList" => found } : {}
+          end
+
+          # @return [Hash{String => Object}] `picture` (the parts that name the file, its
+          #   description and its caption) when the value object is a picture: it has a media key
+          #   and an `alt` and is not a block of a body or a list of mixed blocks
+          def pictured(attribute)
+            object = @by_name[attribute.type.to_s]
+            return {} unless object && !Blocks.body_block?(object) && !listing(attribute).key?("blockList")
+
+            found = Blocks.picture(object)
+            found&.key?("key") && found.key?("alt") ? { "picture" => found } : {}
+          end
+
           # A single (not listed) attribute whose value object holds a list of document blocks.
           def body?(attribute)
             return false if attribute.list?

data/lib/hecks/projections/site/cms_editor/blocks.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # A list of mixed blocks, found by shape: a `list_of` value object that has a discriminator,
+        # a part that is one of a closed set of kinds. The editor draws it as ordered cards.
+        #
+        # The discriminator is a part whose type is a closed set (`one_of`) of one plain value, or,
+        # failing that, a text part that an invariant restricts to a literal list
+        # (`["a", "b"].include?(kind)`). A value object that holds `spans` is a body's block, which
+        # the rich-text widget edits, and is never a block list.
+        #
+        # Which slots each kind uses is read from a declared table: a closed set of rows with the
+        # parts `kind`, `requires` and `uses` whose kinds are among the discriminator's. With no
+        # such table every slot is shown, and the invariants that name a kind only hint which slots
+        # it reads. A limit is read from an invariant or given of the form `<list>.size <= <n>`.
+        module Blocks
+          # The parts a table of rules must have.
+          RULE_PARTS = %w[kind requires uses].freeze
+
+          # The parts that make a value object's picture, in the vocabulary of a body's image block.
+          PICTURE = { "key" => "media_ref", "alt" => "alt", "caption" => "caption" }.freeze
+
+          # An invariant that restricts a text part to a literal list of kinds.
+          LITERALS = /\A\[((?:"[^"]+"(?:, )?)+)\]\.include\?\((\w+)\)\z/
+
+          # An invariant that holds unless the kind is the named one: what the rest of it reads.
+          GUARD = /\A(\w+)(?:\.value)? != "([^"]+)" \|\| (.*)\z/m
+
+          # A limit written as a size comparison.
+          LIMIT = /\A(\w+)\.size <= (\d+)\z/
+
+          module_function
+
+          # @param attribute [Bluebook::Attribute] a declared attribute
+          # @param objects [Hash{String => Bluebook::ValueObject}] the aggregate's value objects
+          # @return [Hash{String => Object}, nil] the block list the attribute is, or nil
+          def of(attribute, objects)
+            item = objects[attribute.type.to_s]
+            return nil unless attribute.list? && item && !body_block?(item)
+
+            found = discriminator(item, objects)
+            found && describe(item, objects, *found)
+          end
+
+          # @return [Boolean] whether the value object holds `spans`, as a body's block does
+          def body_block?(item) = item.attributes.any? { |part| part.name.to_s == "spans" }
+
+          # @return [Array(String, Array<String>), nil] the part and the kinds it is one of
+          def discriminator(item, objects)
+            closed(item, objects) || literal(item)
+          end
+
+          # @return [Array(String, Array<String>), nil] a part typed as a closed set of plain values
+          def closed(item, objects)
+            item.attributes.each do |part|
+              kinds = members_of(objects[part.type.to_s]) unless part.list?
+              return [part.name.to_s, kinds] if kinds && !kinds.empty?
+            end
+            nil
+          end
+
+          # @return [Array<String>, nil] the values of a closed set of one plain part
+          def members_of(set)
+            return nil unless set&.closed_set? && set.attributes.size == 1
+
+            set.members.filter_map { |member| member[set.attributes.first.name]&.to_s }
+          end
+
+          # @return [Array(String, Array<String>), nil] a text part restricted by a literal list
+          def literal(item)
+            found = literals(item).find { |match| item.attributes.any? { |part| part.name.to_s == match[2] && !part.list? } }
+            found && [found[2], found[1].scan(/"([^"]+)"/).flatten]
+          end
+
+          # @return [Array<MatchData>] the invariants that restrict a part to a literal list
+          def literals(item) = item.invariants.filter_map { |rule| LITERALS.match(rule.canonical.to_s) }
+
+          def describe(item, objects, name, kinds)
+            table = rules(objects, kinds)
+            found = { "discriminator" => name, "kinds" => kinds, "limits" => limits(item), "pictures" => pictures(item, objects) }
+            found["rules"] = table if table
+            found["mentions"] = mentions(item, name, kinds) unless table
+            found.reject { |_, value| value.respond_to?(:empty?) && value.empty? }
+          end
+
+          # @return [Hash{String => Hash}, nil] each kind's `requires` and `uses`, from the table
+          def rules(objects, kinds)
+            table = objects.values.find { |object| ruled?(object, kinds) }
+            return nil unless table
+
+            table.members.to_h { |row| [row[:kind].to_s, { "requires" => words(row[:requires]), "uses" => words(row[:uses]) }] }
+          end
+
+          def ruled?(object, kinds)
+            object.closed_set? && (RULE_PARTS - object.attributes.map { |part| part.name.to_s }).empty? &&
+              object.members.all? { |row| kinds.include?(row[:kind].to_s) }
+          end
+
+          def words(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+
+          # @return [Hash{String => Array<String>}] the slots each kind's guarded invariants read
+          def mentions(item, name, kinds)
+            parts = item.attributes.map { |part| part.name.to_s } - [name]
+            guarded(item, name).each_with_object({}) do |(kind, rest), found|
+              next unless kinds.include?(kind)
+
+              found[kind] = ((found[kind] || []) | parts.select { |part| rest.match?(/\b#{Regexp.escape(part)}\b/) })
+            end
+          end
+
+          def guarded(item, name)
+            item.invariants.filter_map do |rule|
+              match = GUARD.match(rule.canonical.to_s)
+              [match[2], match[3]] if match && match[1] == name
+            end
+          end
+
+          # @return [Hash{String => Integer}] each list part of the item and its declared maximum
+          def limits(item)
+            item.invariants.filter_map do |rule|
+              match = LIMIT.match(rule.canonical.to_s)
+              [match[1], match[2].to_i] if match
+            end.to_h
+          end
+
+          # @param commands [Array<Bluebook::Command>] the aggregate's commands
+          # @param name [String] a list attribute's name
+          # @return [Integer, nil] the most the list may hold, from a command's `given`
+          def maximum(commands, name)
+            sizes = commands.flat_map(&:givens).filter_map do |rule|
+              match = LIMIT.match(rule.canonical.to_s)
+              match[2].to_i if match && match[1] == name
+            end
+            sizes.min
+          end
+
+          # @return [Hash{String => Hash}] the value object and each value object its lists hold,
+          #   to the parts that name a picture, for those that have the parts
+          def pictures(item, objects)
+            held = item.attributes.select(&:list?).filter_map { |part| objects[part.type.to_s] }
+            [item, *held].filter_map { |object| (found = picture(object)) && [object.hecks_name, found] }.to_h
+          end
+
+          def picture(object)
+            names = object.attributes.reject(&:list?).map { |part| part.name.to_s }
+            return nil unless names.include?(PICTURE["key"]) && names.include?(PICTURE["alt"])
+
+            PICTURE.select { |_, part| names.include?(part) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/checks.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "preview"
+require_relative "scale_checks"
+require_relative "theme_checks"
+
 module Hecks
   module Projections
     module Site
@@ -23,7 +27,8 @@ module Hecks
           def problems(row, roles, table)
             base = row[:base_path]
             [*path_problems(row, base), *("Editor roles name no role" if roles.empty?), *login_problems(row[:login], table),
-             *media_problems(row)]
+             *media_problems(row), *media_chapter_problems(row), *ThemeChecks.problems(row), *ScaleChecks.problems(row),
+             *Preview.problems(row[:preview].strip)]
           end
 
           # @return [Array<String>] the problems with the base path and the sign-in path
@@ -45,6 +50,14 @@ module Hecks
             found
           end
 
+          # @return [Array<String>] the problem with a `media` chapter that is one the editor edits
+          def media_chapter_problems(row)
+            named = row[:media].strip
+            return [] unless row[:chapter].split(",").map(&:strip).include?(named)
+
+            ["media #{named.inspect} is this editor's own chapter; name another chapter"]
+          end
+
           # The login page is a public row: a visitor with no session must reach it.
           #
           # @return [Array<String>] the problems with the login page

data/lib/hecks/projections/site/cms_editor/clearing.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # A command argument that only clears: the bluebook's way of setting an optional field back
+        # to nothing is an optional argument the command never reads, named as the source of a
+        # `sets <field>, to: :<argument>` mutation (`attribute :nothing, Body, optional: true`,
+        # `sets :draft_body, to: :nothing`). Nobody types into it, so the editor offers no field
+        # for it and the server sends its empty value itself: an empty list, or nothing at all.
+        #
+        # The shape decides it, never a name. The argument is optional, is no attribute of the
+        # aggregate, feeds only plain `sets` mutations of other fields that can be empty (optional
+        # or a list), and no `given` or `ensures` of the command reads it.
+        module Clearing
+          module_function
+
+          # @param command [Bluebook::Command] the command
+          # @param aggregate [Bluebook::Aggregate] the aggregate it belongs to
+          # @return [Array<Bluebook::Attribute>] the command's arguments that only clear
+          def of(command, aggregate)
+            command.attributes.select { |argument| only_clears?(argument, command, aggregate) }
+          end
+
+          # @param shaped [Hash{String => Object}] the command as the editor reads it
+          # @param only [Array<Bluebook::Attribute>] its arguments that only clear
+          # @return [Hash{String => Object}] `shaped` without those arguments, and naming the ones
+          #   that are lists as `empty`, for the editor to send as empty lists
+          def apply(shaped, only)
+            return shaped if only.empty?
+
+            names = only.map { |argument| argument.name.to_s }
+            lists = only.select(&:list?).map { |argument| argument.name.to_s }
+            kept = shaped["attributes"].reject { |attr| names.include?(attr["name"]) }
+            shaped.merge("attributes" => kept, **(lists.empty? ? {} : { "empty" => lists }))
+          end
+
+          # @return [Boolean] whether `argument` is a clearing argument of `command`
+          def only_clears?(argument, command, aggregate)
+            return false if !argument.optional? || named?(aggregate.attributes, argument.name)
+
+            fed = fed_by(argument, command)
+            !fed.empty? && fed.all? { |mutation| clears?(mutation, aggregate) } && !read?(argument, command)
+          end
+
+          # @return [Array<Bluebook::Mutation>] the mutations that take their value from `argument`
+          def fed_by(argument, command)
+            command.mutations.select { |mutation| mutation.source.is_a?(Symbol) && named?([argument], mutation.source) }
+          end
+
+          # @return [Boolean] whether any of `attributes` is called `name`
+          def named?(attributes, name) = attributes.any? { |held| held.name.to_s == name.to_s }
+
+          # @return [Boolean] whether the mutation is a plain set of a field that can be empty
+          def clears?(mutation, aggregate)
+            target = aggregate.attributes.find { |held| held.name.to_s == mutation.target.to_s }
+            mutation.op == :set && !target.nil? && (target.optional? || target.list?)
+          end
+
+          # @return [Boolean] whether a `given` or `ensures` of the command names the argument
+          def read?(argument, command)
+            word = /\b#{Regexp.escape(argument.name.to_s)}\b/
+            [*command.givens, *command.ensures].any? { |rule| word.match?(rule.canonical.to_s) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/color.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # Colour arithmetic for the editor's theme: parsing and writing six-digit hex, moving
+        # between red-green-blue and hue-saturation-lightness, mixing, and the contrast ratio the
+        # web accessibility guidelines define. Pure functions of their inputs, so the theme the
+        # editor is generated with is the same on every run.
+        module Color
+          # A six-digit hex colour with its leading hash.
+          HEX = /\A#[0-9a-fA-F]{6}\z/
+
+          # The step by which `reach` moves a colour's lightness while it searches.
+          STEP = 0.01
+
+          module_function
+
+          # @param value [String] a colour such as `"#1f7a6d"`
+          # @return [Array<Float>] its red, green and blue, each from 0.0 to 1.0
+          def rgb(value) = value.delete_prefix("#").scan(/../).map { |pair| pair.hex / 255.0 }
+
+          # @param channels [Array<Float>] red, green and blue, each from 0.0 to 1.0
+          # @return [String] the colour as lower-case hex
+          def hex(channels)
+            channels.each_with_object(+"#") { |c, text| text << format("%02x", (c.clamp(0.0, 1.0) * 255).round) }
+          end
+
+          # @param value [String] a colour
+          # @return [Array<Float>] hue in degrees, then saturation and lightness from 0.0 to 1.0
+          def hsl(value)
+            red, green, blue = rgb(value)
+            high = [red, green, blue].max
+            low = [red, green, blue].min
+            light = (high + low) / 2.0
+            return [0.0, 0.0, light] if high == low
+
+            spread = high - low
+            sat = light > 0.5 ? spread / (2.0 - high - low) : spread / (high + low)
+            [angle(red, green, blue, high, spread), sat, light]
+          end
+
+          # @param hue [Float] degrees
+          # @param sat [Float] saturation from 0.0 to 1.0
+          # @param light [Float] lightness from 0.0 to 1.0
+          # @return [String] the colour as hex
+          def from_hsl(hue, sat, light)
+            chroma = (1 - ((2 * light) - 1).abs) * sat
+            shift = light - (chroma / 2)
+            hex(sector(hue % 360, chroma, second(hue % 360, chroma)).map { |channel| channel + shift })
+          end
+
+          # @return [Float] the second-largest channel of a colour of the given hue and chroma
+          def second(hue, chroma) = chroma * (1 - (((hue / 60.0) % 2) - 1).abs)
+
+          # @param one [String] a colour
+          # @param other [String] another colour
+          # @param share [Float] how much of `other` goes in, from 0.0 to 1.0
+          # @return [String] the colours mixed channel by channel
+          def mix(one, other, share) = hex(rgb(one).zip(rgb(other)).map { |a, b| (a * (1 - share)) + (b * share) })
+
+          # @param value [String] a colour
+          # @return [Float] its relative luminance as the accessibility guidelines define it
+          def luminance(value)
+            red, green, blue = rgb(value).map { |c| c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055)**2.4 }
+            (0.2126 * red) + (0.7152 * green) + (0.0722 * blue)
+          end
+
+          # @param one [String] a colour
+          # @param other [String] another colour
+          # @return [Float] the contrast ratio, from 1.0 to 21.0
+          def contrast(one, other)
+            high = [luminance(one), luminance(other)].max
+            low = [luminance(one), luminance(other)].min
+            (high + 0.05) / (low + 0.05)
+          end
+
+          # Moves a colour's lightness, a little at a time, until it reads against every background.
+          #
+          # @param value [String] where to start
+          # @param against [Array<String>] backgrounds the colour must read on
+          # @param ratio [Float] the least contrast to reach
+          # @param toward [Symbol] `:darker` or `:lighter`
+          # @return [String] `value` itself when it already reads, else the nearest such colour
+          def reach(value, against, ratio, toward)
+            hue, sat, light = hsl(value)
+            sign = toward == :darker ? -STEP : STEP
+            light += sign until light.round(2).clamp(0.0,
+                                                     1.0) != light.round(2) || reads?(from_hsl(hue, sat, light), against, ratio)
+            from_hsl(hue, sat, light.clamp(0.0, 1.0))
+          end
+
+          # @param value [String] a colour
+          # @param against [Array<String>] backgrounds
+          # @param ratio [Float] the least contrast
+          # @return [Boolean] whether `value` reaches `ratio` on every background
+          def reads?(value, against, ratio) = against.all? { |back| contrast(value, back) >= ratio }
+
+          # @param background [String] a fill
+          # @param light [String] a light foreground to try
+          # @param dark [String] a dark foreground to try
+          # @return [String] whichever reads better on `background`
+          def foreground(background, light, dark) = contrast(light, background) >= contrast(dark, background) ? light : dark
+
+          # @return [Float] the hue, in degrees, of a colour given by its channels
+          def angle(red, green, blue, high, spread)
+            degrees = if high == red then ((green - blue) / spread) % 6
+                      elsif high == green then ((blue - red) / spread) + 2
+                      else ((red - green) / spread) + 4
+                      end
+            degrees * 60.0
+          end
+
+          # @return [Array<Float>] the red, green and blue before lightness is added back
+          def sector(hue, chroma, mid)
+            [[chroma, mid, 0], [mid, chroma, 0], [0, chroma, mid], [0, mid, chroma], [mid, 0, chroma],
+             [chroma, 0, mid]][(hue / 60).floor % 6]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/composition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # Several chapters as one editor: each aggregate keeps the name its chapter gave it and is
+        # stamped with the chapter that declares it, so two aggregates of one name in different
+        # chapters are two aggregates. The stamps exist only when the editor spans more than one
+        # chapter (`chapter`), or when a chapter's roles are limited (`roles`), so an editor of one
+        # open chapter reads exactly as a chapter alone does.
+        module Composition
+          module_function
+
+          # @param chapters [Array<Bluebook::Chapter>] the chapters, in the order the row names them
+          # @param skip [Array<String>] `Name` (in every chapter) or `Chapter::Name` to leave out
+          # @param roles [Hash{String => Array<String>}] the roles each chapter is limited to
+          # @yieldparam aggregate [Bluebook::Aggregate] one aggregate to shape
+          # @yieldreturn [Hash{String => Object}] the aggregate as the editor reads it
+          # @return [Array<Hash{String => Object}>] the shaped aggregates, chapter by chapter
+          def aggregates(chapters, skip:, roles:)
+            many = chapters.size > 1
+            chapters.flat_map do |chapter|
+              kept(chapter, skip).map { |agg| stamp(yield(agg), many ? chapter.name : nil, roles[chapter.name]) }
+            end
+          end
+
+          # @return [Array<Bluebook::Aggregate>] the chapter's aggregates that are not skipped
+          def kept(chapter, skip)
+            chapter.aggregates.reject { |agg| skip.intersect?([agg.hecks_name, "#{chapter.name}::#{agg.hecks_name}"]) }
+          end
+
+          # @return [Hash{String => Object}] `shaped` with its chapter and roles after its name
+          def stamp(shaped, named, roles)
+            extra = { "chapter" => named, "roles" => roles }.compact
+            { "name" => shaped["name"], **extra, **shaped.except("name") }
+          end
+        end
+      end
+    end
+  end
+end