hecks 5.0.0 → 6.0.0

data/lib/hecks/projections/site/site_host.rb

@@ -38,7 +38,7 @@ module Hecks
 
         module_function
 
-        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table
         # @param options [Hash{Symbol => Object}] unused
         # @return [Hash{String => String}] each file's path relative to the project root to its
         #   text;

data/lib/hecks/projections/site/site_root.rb

@@ -43,7 +43,7 @@ module Hecks
 
         module_function
 
-        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table
         # @param options [Hash{Symbol => Object}] unused
         # @return [Hash{String => String}] each file's path relative to the project root to its
         #   text;
@@ -59,11 +59,11 @@ module Hecks
         end
 
         # @return [String, nil] the template, or nil with no `Env` rows
-        def env_template(chapter)
-          vars = ENV_ROWS.read(chapter)
+        def env_template(declaration)
+          vars = ENV_ROWS.read(declaration)
           return nil if vars.empty?
 
-          secrets = SECRETS.read(chapter).first
+          secrets = SECRETS.read(declaration).first
           if secrets.nil? && vars.any? { |var| !var.key?(:value) }
             raise Table::Invalid, "Env rows without a value are secrets; the project declares no Secrets row"
           end

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

@@ -14,6 +14,9 @@ module Hecks
         class Checks
           SWITCH_ID = /\A[a-z][a-z0-9_]*\z/
 
+          # A `global:` source, which names one record.
+          GLOBAL_SOURCE = /\Aglobal:/
+
           # The navigation slots a row sits in.
           #
           # @param row [Row, Link] a row or link
@@ -40,7 +43,7 @@ module Hecks
             @rows.each { |row| check_row(row) }
             @links.each { |link| @navigation.check_link(link) }
             check_unique((@rows + @links).filter_map(&:admin_key), "admin key")
-            check_unique(@rows.map(&:source).grep(/\Aglobal:/), "source")
+            check_unique(@rows.map(&:source).grep(GLOBAL_SOURCE), "source")
           end
 
           private

data/lib/hecks/projections/site/table/navigation_checks.rb

@@ -25,7 +25,7 @@ module Hecks
             unless row.verbs.include?("GET")
               problem(path, "sits in the navigation but answers #{row.verbs.join(",")}; a link is a GET")
             end
-            problem(path, "sits in the navigation and has a parameter") if path.match?(/[:*]/)
+            problem(path, "sits in the navigation and has a parameter") if path.match?(Table::PARAMETER_OR_WILDCARD)
             problem(path, "sits in the navigation and has no label") if row.label.to_s.empty?
             check_heading(row, path)
             check_menu_audience(row, path, slots)
@@ -45,7 +45,7 @@ module Hecks
           private
 
           def check_link_target(link, path)
-            problem(path, "has a parameter; a link is to one page") if link.path.to_s.match?(/[:*]/)
+            problem(path, "has a parameter; a link is to one page") if link.path.to_s.match?(Table::PARAMETER_OR_WILDCARD)
             problem(path, "has no label") if link.label.to_s.empty?
             return unless link.fragment && !link.fragment.match?(FRAGMENT)
 

data/lib/hecks/projections/site/table/row_builder.rb

@@ -14,7 +14,7 @@ module Hecks
                          :seo_title, :edge_verbs, :mobile_heading, :explicit_cache, :edge, keyword_init: true)
 
         # Turns a declared member into a `Row`: checks its fields and their types, fills the
-        # defaults, and checks each closed-set value against the Site chapter's vocabulary.
+        # defaults, and checks each closed-set value against the Site bluebook's vocabulary.
         class RowBuilder
           # The fields a row may carry, with the Ruby class each takes (`:bool` is true or false).
           FIELDS = { path: String, kind: String, render: String, auth: String, methods: String,
@@ -28,7 +28,7 @@ module Hecks
           # What an `edge:` names: the logical id of an `EdgeFunction` row.
           EDGE_NAME = /\A[A-Za-z][A-Za-z0-9]*\z/
 
-          # The value objects of the Site chapter's `Route` aggregate whose members are the closed
+          # The value objects of the Site bluebook's `Route` aggregate whose members are the closed
           # sets, by the row field each constrains.
           VOCABULARY = { kind: "Kind", render: "Render", auth: "Auth", cache: "CacheClass",
                          origin: "Origin", preview: "Preview" }.freeze
@@ -93,7 +93,7 @@ module Hecks
           end
 
           # A `command:` or `query:` source leaves the path to the forms scheme,
-          # `/Chapter/Aggregate/Verb`.
+          # `/Bluebook/Aggregate/Verb`.
           def derived_path(source)
             match = DERIVED_SOURCE.match(source) or return nil
             "/#{match[2]}/#{match[3]}/#{match[4]}"
@@ -137,16 +137,16 @@ module Hecks
             match = DERIVED_SOURCE.match(source)
             unless match || source == "none" || source.match?(NAMED_SOURCE)
               problem(label, "has source #{source.inspect}; use none, global:<slug>, collection:<name>, " \
-                             "command:<Chapter>.<Aggregate>.<Command> or query:<Chapter>.<Aggregate>.<Query>")
+                             "command:<Bluebook>.<Aggregate>.<Command> or query:<Bluebook>.<Aggregate>.<Query>")
             end
             return unless match && @registry
             return if verb_exists?(*match.captures)
 
-            problem(label, "names #{source}, which no attached chapter declares")
+            problem(label, "names #{source}, which no attached bluebook declares")
           end
 
-          def verb_exists?(word, chapter, aggregate, name)
-            found = @registry.bluebook(chapter)&.aggregate(aggregate) or return false
+          def verb_exists?(word, declaration, aggregate, name)
+            found = @registry.bluebook(declaration)&.aggregate(aggregate) or return false
             (word == "command" ? found.commands : found.queries).any? { |verb| verb.hecks_name == name }
           end
 

data/lib/hecks/projections/site/table/row_defaults.rb

@@ -49,7 +49,7 @@ module Hecks
             row.admin_order ||= 0 if row.admin_key
           end
 
-          def list(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+          def list(text) = Hecks::Text.comma_list(text)
 
           def default_cache(row)
             return "no_store" if row.auth != "public" || row.kind == "endpoint"

data/lib/hecks/projections/site/table.rb

@@ -7,11 +7,11 @@ require_relative "table/checks"
 module Hecks
   module Projections
     module Site
-      # A client's route table, read from its chapter and checked against the Site chapter's
+      # A client's route table, read from its bluebook and checked against the Site bluebook's
       # vocabulary.
       #
-      # The rows are the `member` lines of a `value_object "Route"` in any chapter of the project
-      # (the Site chapter's own `Route` aggregate names the fields and the closed sets). This class
+      # The rows are the `member` lines of a `value_object "Route"` in any bluebook of the project
+      # (the Site bluebook's own `Route` aggregate names the fields and the closed sets). This class
       # reads them, fills each row's defaults (the cache class from the auth and kind, the render
       # from the kind, the path from a `command:` or `query:` source), and refuses a table that
       # contradicts itself, naming every problem at once.
@@ -22,6 +22,9 @@ module Hecks
         # The name of the value object a client declares its rows in.
         ROW_OBJECT = "Route"
 
+        # A parameter or a wildcard: what makes a route path stand for more than one page.
+        PARAMETER_OR_WILDCARD = /[:*]/
+
         # The name of the value object a client declares its extra navigation entries in.
         LINK_OBJECT = "NavLink"
 
@@ -31,55 +34,58 @@ module Hecks
         # @return [Array<Link>] the extra navigation entries, in the order the client declared them
         attr_reader :links
 
-        # Finds the one chapter of a project that declares the route table.
+        # Finds the one bluebook of a project that declares the route table.
         #
         # @param registry [Runtime::Registry] the registry the project booted into
-        # @return [Bluebook::Chapter] the chapter holding the `Route` value object with member rows
-        # @raise [Invalid] when no chapter, or more than one, declares one
-        def self.chapter(registry)
-          holders = registry.bluebooks.values.reject { |chapter| chapter.name == "Site" }
-                            .select { |chapter| rows_of(chapter).any? }
-          raise Invalid, "no chapter declares a value_object \"#{ROW_OBJECT}\" with member rows" if holders.empty?
+        # @return [Bluebook::Declaration] the bluebook holding the `Route` value object with member
+        #   rows
+        # @raise [Invalid] when no bluebook, or more than one, declares one
+        def self.declaration(registry)
+          declarations = registry.bluebooks.values
+          holders = declarations.reject { |declaration| declaration.name == "Site" }
+          holders = holders.select { |declaration| rows_of(declaration).any? }
+          raise Invalid, "no bluebook declares a value_object \"#{ROW_OBJECT}\" with member rows" if holders.empty?
           return holders.first if holders.one?
 
-          raise Invalid, "#{holders.size} chapters declare a value_object \"#{ROW_OBJECT}\": " \
+          raise Invalid, "#{holders.size} bluebooks declare a value_object \"#{ROW_OBJECT}\": " \
                          "#{holders.map(&:name).join(", ")}; a project has one route table"
         end
 
-        # Reads and checks one chapter's route table.
+        # Reads and checks one bluebook's route table.
         #
-        # @param chapter [Bluebook::Chapter] the chapter that declares the rows
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the rows
         # @param registry [Runtime::Registry] the registry the project booted into: it holds the
-        #   Site chapter and, for a `command:` or `query:` source, the command or query
+        #   Site bluebook and, for a `command:` or `query:` source, the command or query
         # @return [Table] the checked table
-        # @raise [Invalid] when the Site chapter is not attached or a row is refused
-        def self.read(chapter, registry:)
-          new(rows_of(chapter), vocabulary: vocabulary(registry), registry: registry,
-                                links: rows_of(chapter, LINK_OBJECT))
+        # @raise [Invalid] when the Site bluebook is not attached or a row is refused
+        def self.read(declaration, registry:)
+          new(rows_of(declaration), vocabulary: vocabulary(registry), registry: registry,
+                                links: rows_of(declaration, LINK_OBJECT))
         end
 
-        # @param registry [Runtime::Registry] a registry holding the Site chapter
+        # @param registry [Runtime::Registry] a registry holding the Site bluebook
         # @return [Hash{Symbol => Array<String>}] each constrained field to its allowed values, and
         #   `:http_method` to the verbs a route may answer and `:edge_function_kind` to the kinds of
         #   `EdgeFunction` row
-        # @raise [Invalid] when the registry does not hold the Site chapter
+        # @raise [Invalid] when the registry does not hold the Site bluebook
         def self.vocabulary(registry)
           site = registry.bluebook("Site") or
-            raise Invalid, "the project does not attach the Site chapter (attaches \"Site\")"
+            raise Invalid, "the project does not attach the Site bluebook (attaches \"Site\")"
           route = site.aggregate("Route")
           members = lambda do |name|
-            route.value_objects.find { |object| object.hecks_name == name }.members.map { |member| member.fetch(:value) }
+            closed_set = route.value_objects.find { |object| object.hecks_name == name }
+            closed_set.members.map { |member| member.fetch(:value) }
           end
           closed = RowBuilder::VOCABULARY.transform_values(&members)
           closed.merge(http_method: members.call("HttpMethod"), edge_function_kind: members.call("EdgeFunctionKind"))
         end
 
-        # @param chapter [Bluebook::Chapter] a chapter to search
+        # @param bluebook [Bluebook::Declaration] a bluebook to search
         # @param object [String] the name of the value object whose rows are wanted
         # @return [Array<Hash{Symbol => Object}>] the member rows of its value objects of that name
-        def self.rows_of(chapter, object = ROW_OBJECT)
-          chapter.aggregates.flat_map(&:value_objects)
-                 .select { |candidate| candidate.hecks_name == object }.flat_map(&:members)
+        def self.rows_of(declaration, object = ROW_OBJECT)
+          objects = declaration.aggregates.flat_map(&:value_objects)
+          objects.select { |candidate| candidate.hecks_name == object }.flat_map(&:members)
         end
 
         # @param members [Array<Hash{Symbol => Object}>] the declared member rows

data/lib/hecks/projections/statements/actions.rb

@@ -92,7 +92,10 @@ module Hecks
         end
 
         # A rule's description as written, without a trailing period.
-        def text(rule) = rule.description.to_s.strip.delete_suffix(".")
+        def text(rule)
+          description = rule.description
+          description.to_s.strip.delete_suffix(".")
+        end
       end
     end
   end

data/lib/hecks/projections/statements/relationships.rb

@@ -1,4 +1,5 @@
 require_relative "../plain_english"
+require_relative "../../bluebook/one_of_union"
 
 module Hecks
   module Projections
@@ -14,6 +15,9 @@ module Hecks
         # The built-in value types, which a list names by its field rather than its element.
         PRIMITIVES = %w[String Integer Float TrueClass FalseClass Boolean].freeze
 
+        # A past participle's ending, as a role's first word carries it: "disputed", "drawn".
+        PARTICIPLE = /(ed|en|wn)\z/
+
         module_function
 
         # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct the attribute is on
@@ -23,10 +27,18 @@ module Hecks
           subject = "Each #{PlainEnglish.noun(holder.hecks_name)}"
           return list_sentence(subject, attribute) if attribute.list?
           return nil unless attribute.relationship
+          return union_sentence(subject, holder, attribute) if Bluebook::OneOfUnion.union?(attribute)
 
           "#{subject} #{reference_phrase(attribute)}."
         end
 
+        # "Each hold points at its subject: one account or ATM card." (ADR 0127)
+        def union_sentence(subject, holder, attribute)
+          targets = Bluebook::OneOfUnion.variants(holder, attribute).map { |name| PlainEnglish.noun(name) }
+          verb = attribute.optional? ? "can point at" : "points at"
+          "#{subject} #{verb} its #{PlainEnglish.noun(attribute.name)}: one #{targets.join(" or ")}."
+        end
+
         # "Each order holds a list of toppings." The element is named when the field is not
         # simply its plural: "Each account holds its ledger, a list of ledger entries."
         def list_sentence(subject, attribute)
@@ -48,7 +60,8 @@ module Hecks
 
         # The verb phrase after "Each <holder>".
         def reference_phrase(attribute)
-          target_name = attribute.type.target_name
+          type = attribute.type
+          target_name = type.target_name
           target = PlainEnglish.noun(target_name)
           return own_name_phrase(attribute, target) if Naming.snake(target_name) == attribute.name.to_s
 
@@ -68,7 +81,7 @@ module Hecks
 
         # "can be disputed by one customer", "reports to at most one employee".
         def prepositional_phrase(role, target, optional)
-          if role.split.first.match?(/(ed|en|wn)\z/)
+          if role.split.first.match?(PARTICIPLE)
             optional ? "can be #{role} one #{target}" : "is #{role} one #{target}"
           else
             optional ? "#{role} at most one #{target}" : "#{role} one #{target}"

data/lib/hecks/projections/statements.rb

@@ -17,9 +17,9 @@ module Hecks
 
       module_function
 
-      # Projects every reachable fact in the chapter into its flat sentence list.
+      # Projects every reachable fact in the bluebook into its flat sentence list.
       #
-      # @param bluebook [Bluebook::Chapter] the chapter being projected
+      # @param bluebook [Bluebook::Declaration] the bluebook being projected
       # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
       #   `Projector::Target` calling convention
       # @return [Array<String>] each holder's relationships, invariants, moves and command

data/lib/hecks/projections/vocabulary.rb

@@ -2,11 +2,11 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # Projects lib/hecks/vocabulary.rb from the chapter's `Vocabulary` aggregate.
+    # Projects lib/hecks/vocabulary.rb from the bluebook's `Vocabulary` aggregate.
     #
-    #   Projector.call(:vocabulary, bluebook: <the Bluebook chapter>)
+    #   Projector.call(:vocabulary, bluebook: <the Bluebook bluebook>)
     #
-    # Reads the chapter's judged IR, so the output is what the language holds.
+    # Reads the bluebook's judged IR, so the output is what the language holds.
     module Vocabulary
       extend Projector::Target
 
@@ -62,7 +62,7 @@ module Hecks
 
       # The projector protocol; `options` is unused.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook declaring the
       #   Vocabulary aggregate to project
       # @param options [Hash] unused; accepted to satisfy the registry's call shape
       # @return [String] the rendered `lib/hecks/vocabulary.rb` source
@@ -73,7 +73,7 @@ module Hecks
       # Some sets carry more than a term (`Comparison`, `RefusalTemplate`); taking
       # the first field of those yields duplicated names.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook declaring the
       #   Vocabulary aggregate to read
       # @return [Hash{String => Array<Hash{String => String}>}] each closed set's name,
       #   mapped to its member rows with every field stringified
@@ -87,7 +87,7 @@ module Hecks
       # and `TERMS` constants and the `fetch`/`rows`/`symbols`/`names` reader
       # methods, built from `bluebook`'s declared closed sets.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook declaring the
       #   Vocabulary aggregate to render
       # @return [String] the generated Ruby source, ready to write to disk
       def render(bluebook)

data/lib/hecks/projections/world_skeleton.rb

@@ -0,0 +1,68 @@
+require_relative "../naming"
+
+module Hecks
+  module Projections
+    # A starting `.world` for the domains a registry holds, read off the settings each bound
+    # adapter declares: its fields with their defaults, and its secrets.
+    #
+    # A secret is written as an environment lookup and never as a value. A field with a default is
+    # a comment, because the default already applies when the world gives none. A field without
+    # one is a comment too, so nothing loads with a made-up value. It reads a whole registry, so
+    # it is a plain module and not a registered `Projector` target, and it changes nothing.
+    module WorldSkeleton
+      # What stands in for the skeleton when no bound adapter declares anything.
+      NONE = "# No world is needed: no bound adapter declares a setting or a secret.\n".freeze
+
+      module_function
+
+      # @param registry [Runtime::Registry] a registry whose hecksagons and adapters are loaded
+      # @return [String] one `Hecks.world` block per domain that binds an adapter with settings,
+      #   or `NONE` when no domain does
+      def call(registry:)
+        blocks = registry.hecksagons.values.filter_map { |hecksagon| world_for(registry, hecksagon) }
+        blocks.empty? ? NONE : blocks.join("\n")
+      end
+
+      # @api private
+      def world_for(registry, hecksagon)
+        sections = sections_for(registry, hecksagon)
+        return if sections.empty?
+
+        domain = hecksagon.domain.to_s
+        "Hecks.world #{domain.inspect} do\n  realm #{domain.inspect}\n\n#{sections.join("\n")}end\n"
+      end
+
+      # @api private
+      def sections_for(registry, hecksagon)
+        verb_adapters(hecksagon).filter_map do |verb, name|
+          section(hecksagon.domain.to_s, verb, registry.adapters[name])
+        end
+      end
+
+      # @api private
+      def verb_adapters(hecksagon) = hecksagon.binds.map { |bind| [bind.verb, bind.adapter] }.uniq
+
+      # @api private
+      def section(domain, verb, adapter)
+        return unless adapter && (adapter.fields.any? || adapter.secrets.any?)
+
+        lines = adapter.fields.map { |field| field_line(adapter, field) }
+        lines += adapter.secrets.map { |secret| secret_line(domain, secret) }
+        "  #{verb}(#{adapter.name.inspect}) do\n#{lines.map { |line| "    #{line}\n" }.join}  end\n"
+      end
+
+      # @api private
+      def field_line(adapter, field)
+        return "# #{field} \"...\"  (no default; set it)" unless adapter.defaults.key?(field)
+
+        "# #{field} #{adapter.defaults[field].inspect}  (the default; uncomment to change it)"
+      end
+
+      # @api private
+      def secret_line(domain, secret)
+        variable = "#{Naming.snake(domain)}_#{secret}".upcase
+        "#{secret} ENV.fetch(#{variable.inspect}, \"\")  # secret: set it in the environment"
+      end
+    end
+  end
+end

data/lib/hecks/projections.rb

@@ -9,15 +9,19 @@ end
 
 require_relative "projections/ir"
 require_relative "projections/shape"
+require_relative "projections/command_schema"
 require_relative "projections/oidc"
 require_relative "projections/vocabulary"
 require_relative "projections/parser_table"
+require_relative "projections/phrase_table"
 require_relative "projections/bootstrap_table"
 require_relative "projections/rust_vocabulary"
 require_relative "projections/reference"
 require_relative "projections/model"
 require_relative "projections/diagrams"
 require_relative "projections/statements"
+require_relative "projections/context_relationships"
+require_relative "projections/world_skeleton"
 require_relative "projections/glossary"
 require_relative "projections/deploy/shared"
 require_relative "projections/deploy/lambda"
@@ -28,3 +32,4 @@ require_relative "projections/deploy/vercel"
 require_relative "projections/deploy/smoke"
 require_relative "projections/deploy/template_diff"
 require_relative "projections/site/routes_ts"
+require_relative "projections/rails_app"

data/lib/hecks/projector/cli_audience.rb

@@ -1,10 +1,13 @@
 module Hecks
   module Projector
     # What a launcher's help leaves out and points at for whoever typed the line: the aggregates
-    # only a maintainer of a hecks checkout runs, and the attached chapters worth a line each.
+    # only a maintainer of a hecks checkout runs, and the attached bluebooks worth a line each.
     # `CliProjector` renders the help; the runner decides the audience
     # (`Adapters::Driving::LauncherOptions`).
     module CliAudience
+      # The partial word at the end of a cut line, with the space before it.
+      TRAILING_PARTIAL_WORD = /\s+\S*\z/
+
       module_function
 
       # The specs whose aggregate the audience does not run.
@@ -33,22 +36,22 @@ module Hecks
         ["  #{program} --all                  also list every command (no bluebook is in this folder yet)"]
       end
 
-      # The attached chapters the help points at, one line each, under the call that opens them.
+      # The attached bluebooks the help points at, one line each, under the call that opens them.
       #
-      # @param chapters [Array<Array(String, String)>, nil] each chapter's word and its summary
-      def chapter_lines(program, chapters)
-        return [] if Array(chapters).empty?
+      # @param bluebooks [Array<Array(String, String)>, nil] each bluebook's word and its summary
+      def bluebook_lines(program, declarations)
+        return [] if Array(declarations).empty?
 
-        width = chapters.map { |word, _| word.length }.max
-        ["", "chapters (`#{program} <chapter>` lists a chapter's own commands and queries):",
-         *chapters.map { |word, summary| "  #{word.ljust(width)}  #{clipped(summary)}".rstrip }]
+        width = declarations.map { |word, _| word.length }.max
+        ["", "bluebooks (`#{program} <bluebook>` lists a bluebook's own commands and queries):",
+         *declarations.map { |word, summary| "  #{word.ljust(width)}  #{clipped(summary)}".rstrip }]
       end
 
       # A summary cut to one terminal line, at a word, with an ellipsis where it was cut.
       def clipped(text, limit = 96)
         return text if text.length <= limit
 
-        "#{text[0, limit].sub(/\s+\S*\z/, "")}…"
+        "#{text[0, limit].sub(TRAILING_PARTIAL_WORD, "")}…"
       end
 
       # The line saying the commands for working on hecks itself were left out and how to list

data/lib/hecks/projector/cli_projector/claims.rb

@@ -4,13 +4,13 @@ module Hecks
   module Projector
     module CliProjector
       # The command-line names of a projection: who claims which name, how a command is
-      # qualified, and the launcher names a chapter gives its commands.
+      # qualified, and the launcher names a bluebook gives its commands.
       module Claims
         # Claims the commands and questions of one aggregate and its entities and ports.
         #
         # @param commands [Hash{String => Hash}] the command map, mutated in place
         # @param questions [Hash{String => Hash}] the question map, mutated in place
-        # @param bluebook [Bluebook::Chapter] the booted domain
+        # @param bluebook [Bluebook::Declaration] the booted domain
         # @param aggregate [Bluebook::Aggregate] the aggregate to claim
         # @return [void]
         def claim_aggregate(commands, questions, bluebook, aggregate)
@@ -34,9 +34,9 @@ module Hecks
           end
         end
 
-        # Claims each report under its chapter-qualified name. A report belongs to the chapter,
-        # not an aggregate, so it is addressed `Chapter.Report` (one dot) where a query is
-        # `Chapter::Aggregate.Query`.
+        # Claims each report under its bluebook-qualified name. A report belongs to the bluebook,
+        # not an aggregate, so it is addressed `Bluebook.Report` (one dot) where a query is
+        # `Bluebook::Aggregate.Query`.
         def claim_reports(questions, bluebook)
           bluebook.read_models.each do |model|
             claim(questions, Naming.snake(model.hecks_name), report_spec(bluebook, model))
@@ -69,7 +69,7 @@ module Hecks
         # Sets the display name of every spec in each map: its full name, then renamed by `names`.
         #
         # @param maps [Array<Hash{String => Hash}>] the command and question maps, mutated in place
-        # @param names [Hash, nil] the chapter's launcher names
+        # @param names [Hash, nil] the bluebook's launcher names
         # @return [void]
         def display_names(maps, names)
           maps.each do |specs|
@@ -78,7 +78,7 @@ module Hecks
           end
         end
 
-        # Gives a command the launcher name a chapter's `names` table assigns it.
+        # Gives a command the launcher name a bluebook's `names` table assigns it.
         #
         # The alias replaces the short name in help, so it is listed once; the spelling it
         # replaced keeps working (`:short_was`, read by `aliases`). A table entry naming no
@@ -138,7 +138,7 @@ module Hecks
           parts.join(".")
         end
 
-        # The command's language name, `Chapter::Aggregate[.Entity].Verb`, for help text.
+        # The command's language name, `Bluebook::Aggregate[.Entity].Verb`, for help text.
         def fqn(bluebook, aggregate, command, entity = nil)
           [bluebook.name, "::", aggregate.hecks_name, ".",
            entity ? "#{entity.hecks_name}." : "", command.hecks_name].join

data/lib/hecks/projector/cli_projector/command_specs.rb

@@ -6,6 +6,9 @@ module Hecks
       # The spec hash of each command, port operation, query and report: what the runner parses
       # a call against and what `--help` describes.
       module CommandSpecs
+        # The last `.segment` of a dotted name.
+        LAST_SEGMENT = /\.[^.]+\z/
+
         # The options that name the record a command acts on, before its own arguments.
         # `nil` (a creating command) takes none: there is no record yet.
         # Ports always pass `:aggregate`, since a port is declared on an aggregate.
@@ -86,7 +89,7 @@ module Hecks
         # `Dispatcher#dispatch` looks the head up as a port, so the wire name is
         # `Aggregate.Port.Operation`; the launcher name hides the port.
         def port_wire_name(bluebook, aggregate, port, operation)
-          [fqn(bluebook, aggregate, operation).sub(/\.[^.]+\z/, ""), port.name, operation.hecks_name].join(".")
+          [fqn(bluebook, aggregate, operation).sub(LAST_SEGMENT, ""), port.name, operation.hecks_name].join(".")
         end
 
         # Who issues a port operation, in the direction it runs.
@@ -106,11 +109,11 @@ module Hecks
           "Ask #{port.name} — answers #{operation.answers}, refuses #{operation.refuses}"
         end
 
-        # The conditions that refuse the command when they hold, in the chapter's own words: a
+        # The conditions that refuse the command when they hold, in the bluebook's own words: a
         # lifecycle state mismatch and a missing referenced record per `reference_to`.
         def refusals(command, holder)
           lifecycle_refusals(command, holder) +
-            command.attributes.select(&:reference?).map { |r| "no #{r.type.target_name} has that #{r.name}" }
+            command.attributes.select(&:reference?).map { |r| "no #{r.target_name} has that #{r.name}" }
         end
 
         # The refusal for a lifecycle state the command does not run from, or none.
@@ -118,9 +121,10 @@ module Hecks
           lifecycle = holder.lifecycle
           return [] unless lifecycle
 
-          froms = lifecycle.transitions.filter_map do |name, transition|
+          sources = lifecycle.transitions.filter_map do |name, transition|
             Array(transition.from) if name.to_s == command.hecks_name
-          end.flatten.uniq
+          end
+          froms = sources.flatten.uniq
           froms.empty? ? [] : ["#{lifecycle.field} is not #{froms.join(" or ")}"]
         end