hecks 3.10.0 → 3.12.0

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

@@ -8,6 +8,15 @@
 #   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)
+@@LOG_EXIT_CODE@@
+#
+# 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
@@ -15,6 +24,7 @@
 # cannot run, the roll goes on. SKIP_LOG_CAPTURE=1 skips it; LOG_CAPTURE_SERVICES="a b" limits it to
 # those services (deploy-service.sh sets the one it rolls).
 #
+@@LOG_NOTE@@
 @@USAGE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
@@ -29,6 +39,28 @@ DB_HOST=$(out "$RDS_STACK" DbEndpoint)
 @@DB_SECRET_LINE@@
 [ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 40; }
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
+@@LOG_GROUP_CHECK@@
+
+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
 

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/box/templates/edge.mk.tmpl

@@ -0,0 +1,17 @@
+# GENERATED by hecks deploy project -- re-run it to refresh this file rather than hand-editing.
+# Included by the Makefile beside it; the aliases come from the domain's deployed_to("AwsBox")
+# block (cdn).
+
+EDGE_STACK = @@EDGE_STACK@@
+
+.PHONY: edge
+
+# Creates or updates the CloudFront edge stack in front of the box (run `make stacks` first: the
+# box's AppOriginDomain output is the distribution's origin). The certificate is never created
+# here: issue it in ACM in us-east-1, validate its DNS records, then pass its ARN.
+#   make edge CERTIFICATE_ARN=arn:aws:acm:us-east-1:<account>:certificate/<id>
+edge:
+	@test -n "$(CERTIFICATE_ARN)" || { echo "usage: make edge CERTIFICATE_ARN=arn:aws:acm:us-east-1:..." >&2; exit 1; }
+	aws cloudformation deploy --region @@REGION@@ --template-file edge.yaml --stack-name $(EDGE_STACK) \
+		--parameter-overrides CertificateArn=$(CERTIFICATE_ARN) \
+		AppOriginDomain=$$(aws cloudformation describe-stacks --region @@REGION@@ --stack-name $(BOX_STACK) --query "Stacks[0].Outputs[?OutputKey=='AppOriginDomain'].OutputValue" --output text)

data/lib/hecks/projections/deploy/box/templates/edge.yaml.tmpl

@@ -0,0 +1,65 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >
+  The CloudFront edge of @@STACK@@: one distribution in front of the app box. Its only origin is the
+  box's public DNS name over plain http on port 80, and every request to it carries the origin secret
+  header the box's proxy checks. Nothing is cached: the origin decides what a response means.
+
+Parameters:
+  AppOriginDomain:
+    Type: String
+    AllowedPattern: ".+"
+    ConstraintDescription: the box stack's AppOriginDomain output
+    Description: DNS name of the app box, the distribution's only origin.
+  CertificateArn:
+    Type: String
+    AllowedPattern: "arn:aws:acm:us-east-1:.+"
+    ConstraintDescription: an ACM certificate in us-east-1 that covers every alias
+    Description: >
+      An issued ACM certificate in us-east-1 that covers every name in DomainNames. It is never created
+      here: DNS validation is a step an operator performs.
+  DomainNames:
+    Type: CommaDelimitedList
+    Default: "@@ALIASES@@"
+    Description: The host names the distribution answers on.
+
+Resources:
+  Distribution:
+    Type: AWS::CloudFront::Distribution
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      DistributionConfig:
+        Enabled: true
+        HttpVersion: http2
+        IPV6Enabled: true
+        Aliases: !Ref DomainNames
+        ViewerCertificate:
+          AcmCertificateArn: !Ref CertificateArn
+          SslSupportMethod: sni-only
+          MinimumProtocolVersion: TLSv1.2_2021
+        Origins:
+          - Id: BoxOrigin
+            DomainName: !Ref AppOriginDomain
+            OriginCustomHeaders:
+              # Resolved by CloudFormation from Secrets Manager when the stack deploys, so the value
+              # never appears on a command line or in this file.
+              - HeaderName: @@ORIGIN_HEADER@@
+                HeaderValue: "{{resolve:secretsmanager:@@ORIGIN_SECRET@@:SecretString}}"
+            CustomOriginConfig:
+              OriginProtocolPolicy: http-only
+              OriginSSLProtocols: [TLSv1.2]
+        DefaultCacheBehavior:
+          TargetOriginId: BoxOrigin
+          ViewerProtocolPolicy: redirect-to-https
+          AllowedMethods: [GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE]
+          CachedMethods: [GET, HEAD]
+          Compress: true
+          CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad # Managed-CachingDisabled
+          OriginRequestPolicyId: 216adef6-5c7f-47e4-b989-5492eafa07d3 # Managed-AllViewer
+
+Outputs:
+  DistributionId:
+    Value: !Ref Distribution
+  DistributionDomainName:
+    Description: Point each alias's DNS record (CNAME or alias) at this name.
+    Value: !GetAtt Distribution.DomainName

data/lib/hecks/projections/deploy/box/templates/log-group.yaml.tmpl

@@ -0,0 +1,12 @@
+  # Every container's log, one stream per service. The group is made here and not by Docker
+  # (awslogs-create-group is "false"), so the role below needs no right to create groups, and the
+  # retention is a declaration. A production group outlives the stack: the evidence a container
+  # wrote must not go with a deleted stack.
+  BoxLogGroup:
+    Type: AWS::Logs::LogGroup
+    DeletionPolicy: !If [IsProduction, Retain, Delete]
+    UpdateReplacePolicy: !If [IsProduction, Retain, Delete]
+    Properties:
+      LogGroupName: @@LOG_GROUP@@
+      RetentionInDays: @@RETENTION_DAYS@@
+

data/lib/hecks/projections/deploy/box/templates/log-policy.yaml.tmpl

@@ -0,0 +1,7 @@
+        - PolicyName: write-logs
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: [logs:CreateLogStream, logs:PutLogEvents, logs:DescribeLogStreams]
+                Resource: !GetAtt BoxLogGroup.Arn

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

@@ -13,6 +13,7 @@
 # When the world names origin_env, the named origin secret is compared with those variables in the
 # task definition and the render refuses on any difference (Caddy checks the CDN's header against
 # the secret; the containers check it against their own copy). Values are never printed.
+@@COMPOSE_LOG_NOTE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 DB_HOST=${1:?rds endpoint}
@@ -36,7 +37,7 @@ if [ -n "$ORIGIN_ENV" ]; then
 fi
 
 jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
-  def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
+  @@LOG_DEF@@
   def env(c): ((c.environment // []) | map({(.name): .value}) | add // {})
     | (if has("DB_HOST") then .DB_HOST = $host | .DB_SECRET_ARN = $secret else . end);
   . as $in
@@ -44,16 +45,16 @@ jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
       ($in.services | with_entries(.value |= (. as $s
         | ($def | map(select(.name == $s.name)) | first) as $c
         | if $c == null then error("task definition has no container named " + $s.name) else
-            {image: $c.image, network_mode: "host", restart: "unless-stopped", logging: log,
+            {image: $c.image, network_mode: "host", restart: "unless-stopped", logging: @@LOG_SERVICE@@,
              environment: ({PORT: ($s.port | tostring)} + env($c))}
             + (if (($c.secrets // []) | length) > 0 then {env_file: [($s.name + ".secrets.env")]} else {} end)
           end)))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
-                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
                  + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
       + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
                   command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: log}} else {} end))}' \
+                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
   "$HERE/services.json" > compose.json
 
 jq --argjson def "$DEF" '. as $in

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

@@ -6,6 +6,7 @@
 # Tags default to "latest". Every container gets DB_HOST, DB_NAME, DB_SECRET_ARN and PORT, and runs on the
 # box's own network, so the proxy reaches each one on 127.0.0.1:<port>. Secrets named in services.json
 # are written to secrets.json for fetch-secrets.sh to resolve on the box.
+@@COMPOSE_LOG_NOTE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 DB_HOST=${1:?rds endpoint}
@@ -18,20 +19,20 @@ ECR="$ACCOUNT.dkr.ecr.$REGION.amazonaws.com"
 TAGS=$(printf '%s\n' "$@" | jq -R 'select(length > 0) | split("=") | {(.[0]): .[1]}' | jq -s 'add // {}')
 
 jq --arg ecr "$ECR" --argjson tags "$TAGS" --arg host "$DB_HOST" --arg secret "$DB_SECRET" --arg db "@@DB_NAME@@" '
-  def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
+  @@LOG_DEF@@
   . as $in
   | {services: (
       ($in.services | with_entries(.value |= (
         {image: ($ecr + "/" + .repository + ":" + ($tags[.name] // "latest")),
-         network_mode: "host", restart: "unless-stopped", logging: log,
+         network_mode: "host", restart: "unless-stopped", logging: @@LOG_SERVICE@@,
          environment: ({PORT: (.port | tostring), DB_HOST: $host, DB_NAME: $db, DB_SECRET_ARN: $secret} + .env)}
         + (if (.secrets | length) > 0 then {env_file: [(.name + ".secrets.env")]} else {} end))))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
-                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
                  + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
       + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
                   command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: log}} else {} end))}' \
+                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
   "$HERE/services.json" > compose.json
 
 jq '. as $in

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

@@ -5,10 +5,12 @@ require_relative "box/hosting"
 require_relative "box/roll_recipe"
 require_relative "box/caddy"
 require_relative "box/access"
+require_relative "box/logging"
 require_relative "box/stack_yaml"
 require_relative "box/compose"
 require_relative "box/shared_database"
 require_relative "box/roll_scripts"
+require_relative "box/edge"
 
 module Hecks
   module Projections
@@ -21,10 +23,12 @@ module Hecks
         extend Projector::Target
         extend Caddy
         extend Access
+        extend Logging
         extend StackYaml
         extend Compose
         extend SharedDatabase
         extend RollScripts
+        extend Edge
 
         projects_as :aws_box, needs_world: true, emits: :files
 
@@ -123,7 +127,15 @@ module Hecks
             volume_gb: { value: settings.fetch(:volume_gb, 30) },
             database_class: { value: settings.fetch(:database_class, "db.t4g.small") },
             storage_gb: { value: settings.fetch(:storage_gb, 20) }
-          }
+          }.merge(cdn_arguments(settings[:cdn]))
+        end
+
+        # @param cdn [Hash{Symbol => Object}, nil] the world's `cdn` setting
+        # @return [Hash{Symbol => Array}] the `cdn_aliases` argument, or nothing without a `cdn`
+        def cdn_arguments(cdn)
+          return {} unless cdn.is_a?(Hash) && cdn[:aliases].is_a?(Array)
+
+          { cdn_aliases: cdn[:aliases].map { |name| { value: name } } }
         end
 
         # @param plan [Settings::Plan] the resolved settings
@@ -136,8 +148,8 @@ module Hecks
             "render-compose.sh" => render_compose_sh(plan, region),
             "fetch-secrets.sh" => File.read(File.join(TEMPLATE_DIR, "fetch-secrets.sh")),
             "deploy-box.sh" => deploy_box_sh(plan, region),
-            "Makefile" => makefile(plan)
-          }.merge(database_files(plan)).merge(migration_files(plan))
+            "Makefile" => makefile(plan, region)
+          }.merge(database_files(plan)).merge(migration_files(plan)).merge(edge_files(plan, region))
             .then { |files| Hosting.extend_files(files, plan: plan, region: region) }
         end
 

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