hecks 5.0.0 → 7.0.0

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

@@ -16,15 +16,18 @@ module Hecks
       # from its queries, a detail page per instance and a form per command.
       #
       # It is generic by aggregate. The pages and forms are not written per aggregate; they read
-      # `src/schema.ts`, which is the domain chapter's aggregates, attributes, value objects,
+      # `src/schema.ts`, which is the domain bluebook's aggregates, attributes, value objects,
       # lifecycles, commands and queries as one typed constant. The domain holds no editor data: the
       # editor reads and dispatches through the host like any other client, and the output is a pure
-      # function of the chapter and the `Editor` row, so `--check` can hold it current.
+      # function of the bluebook and the `Editor` row, so `--check` can hold it current.
       module CmsEditor
         extend Projector::Target
 
         projects_as :site_cms_editor, emits: :files
 
+        # A `__NAME__` placeholder, captured with its newline when it stands alone on its line.
+        PLACEHOLDER = /^(__[A-Z_]+__)\n|__[A-Z_]+__/
+
         # Where the template files are.
         TEMPLATES = File.join(__dir__, "cms_editor", "templates")
 
@@ -42,14 +45,14 @@ module Hecks
           src/ui/blocks.ts src/ui/block_list.js src/browser/blocks.js
         ].freeze
 
-        # The files only an editor of a chapter with a picture aggregate has: the upload, the
+        # The files only an editor of a bluebook with a picture aggregate has: the upload, the
         # storage port with its local-disk adapter, and the picker the rich-text editor opens.
         MEDIA_FILES = %w[
           src/media/sniff.ts src/media/multipart.ts src/media/storage.ts src/media/handler.ts src/browser/media_picker.js
         ].freeze
 
         # What `app.ts` and the body editor hold for a picture upload; each is left out when the
-        # chapter has none.
+        # bluebook has none.
         MEDIA_LINES = {
           "__MEDIA_IMPORT__"  => ["import { mediaHandler, mediaOpen } from \"./media/handler.ts\";",
                                   "import type { MediaStorage } from \"./media/storage.ts\";"].join("\n"),
@@ -66,22 +69,22 @@ module Hecks
 
         # Renders the editor's files for a project that declares an `Editor` row.
         #
-        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table and the row
-        # @param options [Hash{Symbol => Object}] `:domain_chapters` the chapters to edit, in the
-        #   order the row names them (`:domain_chapter` for one);
-        #   `:media_chapter` the chapter the row's `media` names, whose picture aggregate the
-        #   pictures use; `:table` the checked route table, when the login page is to be checked
-        #   against it
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table and row
+        # @param options [Hash{Symbol => Object}] `:domain_bluebooks` the bluebooks to edit, in the
+        #   order the row names them (`:domain_bluebook` for one); `:media_bluebook` the bluebook
+        #   the row's `media` names, whose picture aggregate the pictures use; `:table` the checked
+        #   route table, when the login page is to be checked against it
         # @return [Hash{String => String}] each file's path relative to the editor's directory to
         #   its text; empty when the project declares no `Editor` row
         # @raise [Table::Invalid] when the row is refused
-        # @raise [ArgumentError] when the chapter has no aggregate to edit
+        # @raise [ArgumentError] when the bluebook has no aggregate to edit
         def call(bluebook:, options: {})
           setting = Setting.read(bluebook, table: options[:table])
           return {} unless setting
 
-          chapters = options[:domain_chapters] || options.fetch(:domain_chapter)
-          schema = Schema.read(chapters, skip: setting.skip, pictures: options[:media_chapter], roles: setting.chapter_roles)
+          declarations = options[:domain_bluebooks] || options.fetch(:domain_bluebook)
+          schema = Schema.read(declarations, skip: setting.skip, pictures: options[:media_bluebook],
+roles: setting.bluebook_roles)
           media = schema.key?("media")
           tokens = tokens(setting, schema, media)
           [*FILES, *(MEDIA_FILES if media)].to_h { |path| [path, fill(File.read(File.join(TEMPLATES, "#{path}.tmpl")), tokens)] }
@@ -92,7 +95,7 @@ module Hecks
           setting.tokens.merge(look_tokens(setting, schema), "__SCHEMA__" => Pretty.generate(schema), **media_tokens(media))
         end
 
-        # @param media [Boolean] whether the chapter has a picture aggregate
+        # @param media [Boolean] whether the bluebook has a picture aggregate
         # @return [Hash{String => String}] each media placeholder to its text, empty when none
         def media_tokens(media)
           return MEDIA_LINES if media
@@ -101,7 +104,7 @@ module Hecks
         end
 
         # @param setting [Setting] the checked row
-        # @param schema [Hash{String => Object}] the chapter as the editor reads it
+        # @param schema [Hash{String => Object}] the bluebook as the editor reads it
         # @return [Hash{String => String}] the brand, the icon sprite and the theme's colours
         def look_tokens(setting, schema)
           { "__BRAND__" => JSON.generate(setting.brand || schema["domain"]), "__ICONS__" => Icons.sprite,
@@ -114,7 +117,7 @@ module Hecks
         #   like a placeholder is left as it is; a placeholder alone on its line whose text is empty
         #   takes the line with it
         def fill(text, tokens)
-          text.gsub(/^(__[A-Z_]+__)\n|__[A-Z_]+__/) do
+          text.gsub(PLACEHOLDER) do
             line = Regexp.last_match(1)
             token = line || Regexp.last_match(0)
             replacement(tokens.fetch(token, token), alone: !line.nil?)

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

@@ -31,7 +31,7 @@ module Hecks
 
           # @param edge [Edge] the edge being read, its rows set
           # @param rows [Array<Table::Row>] the route table's rows
-          # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+          # @param vocabulary [Hash{Symbol => Array<String>}] the Site bluebook's closed sets
           # @param problems [Array<String>] collects each problem found, one line each
           # @param template_named [Boolean] whether the caller names the template itself
           def initialize(edge, rows, vocabulary, problems, template_named: false)

data/lib/hecks/projections/site/edge/function_checks.rb

@@ -19,7 +19,7 @@ module Hecks
 
           # @param edge [Edge] the edge being read, its rows set
           # @param rows [Array<Table::Row>] the route table's rows
-          # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+          # @param vocabulary [Hash{Symbol => Array<String>}] the Site bluebook's closed sets
           # @param problems [Array<String>] collects each problem found, one line each
           def initialize(edge, rows, vocabulary, problems)
             @edge = edge

data/lib/hecks/projections/site/edge/function_code.rb

@@ -15,6 +15,9 @@ module Hecks
         # CloudFormation expression. The checks refuse such a row when it is read, and `code`
         # refuses again, since it is the last step before the text is written.
         module FunctionCode
+          # A lower-case letter or digit followed by a capital: where two camel-case words meet.
+          WORD_BOUNDARY = /([a-z0-9])([A-Z])/
+
           # A lowercase hostname of at least two labels, as the host header is compared after
           # lowercasing.
           HOST = /\A([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}\z/
@@ -50,7 +53,7 @@ module Hecks
 
           # @param name [String] a function's logical id
           # @return [String] the hyphenated name the function carries, such as `host-redirect`
-          def kebab(name) = name.gsub(/([a-z0-9])([A-Z])/, '\1-\2').downcase
+          def kebab(name) = name.gsub(WORD_BOUNDARY, '\1-\2').downcase
 
           # @param function [Edge::Function] a `redirect_host` row
           # @return [String] the resource, from the left margin, ending in a newline

data/lib/hecks/projections/site/edge/pattern.rb

@@ -11,11 +11,14 @@ module Hecks
         # stands for `*`. Both services treat `*` as any run of characters, `/` included, and `?` as
         # one character, and match the whole path, so a pattern without either matches one path.
         module Pattern
+          # A route parameter: a colon, then an identifier, as in `:slug`.
+          PARAMETER = /:[A-Za-z_]\w*/
+
           module_function
 
           # @param path [String] a route path such as `/blog/:slug.html` or `/cms/*`
           # @return [String] the pattern the edge reads for it, `/blog/*.html` for the first
-          def edge(path) = path.gsub(/:[A-Za-z_]\w*/, "*")
+          def edge(path) = path.gsub(PARAMETER, "*")
 
           # @param pattern [String] an edge pattern
           # @return [Regexp] what it matches, from the start of a path to its end

data/lib/hecks/projections/site/edge/route_checks.rb

@@ -16,7 +16,7 @@ module Hecks
 
           # @param edge [Edge] the edge being read, its rows set
           # @param rows [Array<Table::Row>] the route table's rows
-          # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+          # @param vocabulary [Hash{Symbol => Array<String>}] the Site bluebook's closed sets
           # @param problems [Array<String>] collects each problem found, one line each
           def initialize(edge, rows, vocabulary, problems)
             @edge = edge
@@ -43,7 +43,7 @@ module Hecks
           end
 
           def check_listener
-            problem("EdgeRule", "rows need an Edge row with listener:") if @edge.rules.any? && !@edge.setting&.listener
+            problem("EdgeRule", "rows need an Edge row with listener:") if @edge.rules.any? && !@edge.listener
           end
 
           # With `alb: false` nothing routes by listener rule, so a rule row, or a route that names

data/lib/hecks/projections/site/edge/rules.rb

@@ -51,7 +51,7 @@ module Hecks
             elsif paths.include?("/*") && paths.size > 1
               problem("EdgeRule #{rule.rule}", "carries /*, which every other path it lists is part of")
             end
-            limit = @edge.setting.secret_header ? VALUES - 1 : VALUES
+            limit = @edge.secret_header ? VALUES - 1 : VALUES
             return if paths.size <= limit
 
             problem("EdgeRule #{rule.rule}", "carries #{paths.size} paths; a rule holds at most #{limit} " \

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

@@ -17,7 +17,7 @@ module Hecks
       #
       # The routes are the table's own `Route` rows. What a table cannot know, the names a template
       # gives its policies, origins, target groups and listener, a project declares as `member`
-      # rows of five more value objects of the same chapter: `Edge` (the template and listener),
+      # rows of five more value objects of the same bluebook: `Edge` (the template and listener),
       # `EdgePolicy`, `EdgeOrigin`, `EdgeRule` and `EdgeFunction` (a viewer-request function a route
       # names with `edge:`). `docs/site-routes.md` lists their fields. A project that declares none
       # of the five has no edge to project.
@@ -38,7 +38,7 @@ module Hecks
 
           private
 
-          def split(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+          def split(text) = Hecks::Text.comma_list(text)
         end
 
         # The value objects a project declares its edge rows in, by the kind of record each holds.
@@ -78,18 +78,18 @@ module Hecks
         # @return [Array<Hash{Symbol => Object}>] each listener rule with the paths it carries
         attr_reader :listener_rules
 
-        # Reads and checks the edge a chapter declares.
+        # Reads and checks the edge a bluebook declares.
         #
-        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table
         # @param table [Table] the checked route table
-        # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+        # @param vocabulary [Hash{Symbol => Array<String>}] the Site bluebook's closed sets
         # @param template [String, nil] the template the caller names, which stands in for the
         #   `Edge` row's own `template:`
-        # @return [Edge, nil] the checked edge, or nil when the chapter declares none and no route
+        # @return [Edge, nil] the checked edge, or nil when the bluebook declares none and no route
         #   names an edge function
         # @raise [Table::Invalid] when a row is refused or the edge contradicts the routes
-        def self.read(chapter, table:, vocabulary:, template: nil)
-          declared = OBJECTS.transform_values { |name| Table.rows_of(chapter, name) }
+        def self.read(declaration, table:, vocabulary:, template: nil)
+          declared = OBJECTS.transform_values { |name| Table.rows_of(declaration, name) }
           return nil if declared.values.all?(&:empty?) && table.rows.none?(&:edge)
 
           problems = []
@@ -141,6 +141,12 @@ module Hecks
         #   unless the `Edge` row says `alb: false`
         def alb? = setting.nil? || setting.alb != false
 
+        # @return [String, nil] the listener the `Edge` row names, or `nil` without an `Edge` row
+        def listener = setting&.listener
+
+        # @return [String, nil] the secret header the `Edge` row names
+        def secret_header = setting.secret_header
+
         # @param name [String] a logical id
         # @return [Function, nil] the function row of that name
         def function(name) = functions.find { |candidate| candidate.name == name }

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

@@ -120,8 +120,8 @@ module Hecks
         def intrinsic?(value) = value.is_a?(String) && value.start_with?("!")
 
         def unresolved(entries)
-          entries.flat_map { |entry| entry.values_at(:cache, :request, :response) }
-                 .select { |value| intrinsic?(value) && !@refs.key?(value) }.uniq.sort
+          policy_ids = entries.flat_map { |entry| entry.values_at(:cache, :request, :response) }
+          policy_ids.select { |value| intrinsic?(value) && !@refs.key?(value) }.uniq.sort
         end
 
         def resolve(entry) = entry.transform_values { |value| intrinsic?(value) ? @refs.fetch(value, value) : value }

data/lib/hecks/projections/site/payload/fields/definitions.rb

@@ -43,7 +43,7 @@ module Hecks
             end
 
             def options(text)
-              items = text.split(",").map(&:strip).reject(&:empty?).map do |item|
+              items = Hecks::Text.comma_list(text).map do |item|
                 value, label = item.split("=", 2)
                 label ? "{ label: #{label.to_json}, value: #{value.to_json} }" : value.to_json
               end

data/lib/hecks/projections/site/payload/lifecycle/text.rb

@@ -39,7 +39,7 @@ module Hecks
             }
 
             export interface Spec<S extends Instance, I extends { slug: string }> {
-              /** The aggregate as the host names it, chapter first: "Club::Event". */
+              /** The aggregate as the host names it, bluebook first: "Club::Event". */
               aggregate: string;
               /** Its instances in an answer, keyed by slug. */
               read: (answer: Answer) => S[];

data/lib/hecks/projections/site/payload/model.rb

@@ -4,7 +4,7 @@ module Hecks
   module Projections
     module Site
       module Payload
-        # What the generators read from a domain chapter about one aggregate the content system
+        # What the generators read from a domain bluebook about one aggregate the content system
         # drives: its attributes with the shape each takes over the wire, the command that creates
         # it, the lifecycle edges, and the role its commands declare.
         #
@@ -24,39 +24,43 @@ module Hecks
           # each is.
           SINGLE = { "value" => :value, "url" => :url, "address" => :address }.freeze
 
-          # @param chapter [Bluebook::Chapter] the domain chapter
+          # @param bluebook [Bluebook::Declaration] the domain bluebook
           # @param skip [Array<String>] aggregates to leave out
           # @return [Array<Aggregate>] each aggregate with a lifecycle and a creating command
           # @raise [ArgumentError] when such an aggregate cannot be driven
-          def self.read(chapter, skip: [])
-            chapter.aggregates.select { |agg| agg.lifecycle && !skip.include?(agg.hecks_name) }
-                   .map { |agg| new(chapter, agg).aggregate }
+          def self.read(declaration, skip: [])
+            declaration.aggregates.select { |agg| agg.lifecycle && !skip.include?(agg.hecks_name) }
+                       .map { |agg| new(declaration, agg).aggregate }
           end
 
           # @return [Aggregate] the aggregate's model
           attr_reader :aggregate
 
-          def initialize(chapter, agg)
-            @chapter = chapter
+          def initialize(declaration, agg)
+            @declaration = declaration
             @agg = agg
-            @aggregate = Aggregate.new(noun: agg.hecks_name, fqn: "#{chapter.name}::#{agg.hecks_name}", create: create,
+            @aggregate = Aggregate.new(noun: agg.hecks_name, fqn: "#{declaration.name}::#{agg.hecks_name}", create: create,
                                        edges: edges, attrs: attrs, identity: agg.identified_by.to_s, role: role)
           end
 
           private
 
+          def lifecycle = @agg.lifecycle
+
           def create
             command = @agg.commands.find(&:creates?)
             raise ArgumentError, "#{@agg.hecks_name} has no command that creates it" unless command
-            raise ArgumentError, "#{@agg.hecks_name}'s lifecycle has no default status" unless @agg.lifecycle.default
 
-            { verb: command.hecks_name, status: @agg.lifecycle.default }
+            status = lifecycle.default
+            raise ArgumentError, "#{@agg.hecks_name}'s lifecycle has no default status" unless status
+
+            { verb: command.hecks_name, status: status }
           end
 
           def edges
             creating = @agg.commands.select(&:creates?).map(&:hecks_name)
             map = Hash.new { |hash, key| hash[key] = {} }
-            @agg.lifecycle.transitions.each { |verb, move| add_edges(map, verb, move) unless creating.include?(verb) }
+            lifecycle.transitions.each { |verb, move| add_edges(map, verb, move) unless creating.include?(verb) }
             map.transform_values(&:dup)
           end
 
@@ -77,7 +81,7 @@ module Hecks
           end
 
           def attrs
-            @agg.attributes.reject { |attribute| attribute.name == @agg.lifecycle.field }.map { |attribute| attr(attribute) }
+            @agg.attributes.reject { |attribute| attribute.name == @agg.lifecycle_field }.map { |attribute| attr(attribute) }
           end
 
           def attr(attribute)

data/lib/hecks/projections/site/payload/specs.rb

@@ -59,12 +59,14 @@ module Hecks
           def heading(agg) = "// ---- #{agg.noun} ----"
 
           def composites(agg)
-            agg.attrs.select { |attr| attr.shape == :composite }.map do |attr|
+            composite_attrs(agg).map do |attr|
               fields = attr.parts.map { |part| "  #{part.ts}: string;" }.join("\n")
               "export interface #{attr.type} {\n#{fields}\n}"
             end.join("\n\n")
           end
 
+          def composite_attrs(agg) = agg.attrs.select { |attr| attr.shape == :composite }
+
           def input_type(agg)
             fields = agg.attrs.map { |attr| "  #{attr.ts}: #{ts_type(attr)};" }.join("\n")
             "export interface #{agg.noun}Input {\n#{fields}\n}"
@@ -84,7 +86,7 @@ module Hecks
           end
 
           def composite_readers(agg)
-            agg.attrs.select { |attr| attr.shape == :composite }.map do |attr|
+            composite_attrs(agg).map do |attr|
               parts = attr.parts.map { |part| "#{part.ts}: text(s.#{part.name})" }.join(", ")
               <<~TS.chomp
                 const #{reader(agg, attr)} = (value: unknown): #{attr.type}[] =>

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

@@ -16,7 +16,7 @@ module Hecks
       # the command that creates it) and the Payload field definitions with the readers that turn a
       # saved document back into an input.
       #
-      # A `Payload` row names the domain, its chapter and where the files go; `PayloadField` rows
+      # A `Payload` row names the domain, its bluebook and where the files go; `PayloadField` rows
       # say what the editor needs that an attribute's shape cannot (a date picker, a choice list,
       # an upload, a relation). The domain stays free of the content system: it is read, never
       # annotated.
@@ -27,9 +27,9 @@ module Hecks
 
         # The `Payload` row.
         PAYLOAD = RootRows.new("Payload",
-                               fields:   { domain: String, chapter: String, out: String, hecks: String, helpers: String,
+                               fields:   { domain: String, bluebook: String, out: String, hecks: String, helpers: String,
 skip: String },
-                               required: %i[domain chapter],
+                               required: %i[domain bluebook],
                                defaults: { out: "cms/src/generated", hecks: "cms/src/driver/hecks",
                                            helpers: "cms/src/collections/hooks/content", skip: "" })
 
@@ -44,8 +44,9 @@ skip: String },
 
         module_function
 
-        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table and the rows
-        # @param options [Hash{Symbol => Object}] `:domain_chapter` the domain's chapter, or nil
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table and the
+        #   rows
+        # @param options [Hash{Symbol => Object}] `:domain_bluebook` the domain's bluebook, or nil
         # @return [Hash{String => String}] each file's path relative to the project root to its
         #   text; empty when the project declares no `Payload` row
         # @raise [Table::Invalid] when a row is refused
@@ -54,9 +55,9 @@ skip: String },
           row = PAYLOAD.read(bluebook).first
           return {} unless row
 
-          chapter = options.fetch(:domain_chapter)
-          aggregates = Payload::Model.read(chapter, skip: row[:skip].split(",").map(&:strip))
-          raise ArgumentError, "the #{chapter.name} chapter has no aggregate with a lifecycle to drive" if aggregates.empty?
+          declaration = options.fetch(:domain_bluebook)
+          aggregates = Payload::Model.read(declaration, skip: row[:skip].split(",").map(&:strip))
+          raise ArgumentError, "the #{declaration.name} bluebook has no aggregate with a lifecycle to drive" if aggregates.empty?
 
           files(row, aggregates, FIELD.read(bluebook))
         end

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

@@ -35,6 +35,15 @@ module Hecks
         # The redirect statuses.
         REDIRECTS = [301, 302, 303, 307, 308].freeze
 
+        # A Cache-Control value that lets a shared cache keep the response.
+        SHAREABLE = /public|max-age=[1-9]/
+
+        # A Cache-Control value that keeps the response out of a shared cache.
+        UNSHAREABLE = /no-store|private/
+
+        # A page's canonical link tag.
+        CANONICAL_LINK = /<link[^>]+rel=["']canonical["']/i
+
         # @param rows [Array<Table::Row>] the checked rows of a route table
         # @param run [String] the run's name, which makes the missing path unique to it
         def initialize(rows, run:)
@@ -64,7 +73,7 @@ module Hecks
 
         private
 
-        def askable?(row) = !row.path.empty? && !row.path.match?(/[:*]/)
+        def askable?(row) = !row.path.empty? && !row.path.match?(Table::PARAMETER_OR_WILDCARD)
 
         def for_row(row)
           return [off(row)] if row.off
@@ -105,14 +114,14 @@ module Hecks
           return nil if response.status >= 400
 
           control = response.headers["cache-control"].to_s
-          return nil unless control.match?(/public|max-age=[1-9]/) && !control.match?(/no-store|private/)
+          return nil unless control.match?(SHAREABLE) && !control.match?(UNSHAREABLE)
 
           "the redirect is cacheable (Cache-Control: #{control})"
         end
 
         def page(response)
           return "expected 200, got HTTP #{response.status}" unless response.status == 200
-          return nil if response.body.to_s.match?(/<link[^>]+rel=["']canonical["']/i)
+          return nil if response.body.to_s.match?(CANONICAL_LINK)
 
           "the page has no canonical link"
         end

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

@@ -33,11 +33,19 @@ module Hecks
             [
               "#{indent}# BEGIN GENERATED site_cdn #{name} (hecks site site_projection.project_site; " \
               "edit the Route and Edge rows). Do not hand-edit.",
-              block.each_line.map { |line| line.strip.empty? ? line : "#{indent}#{line}" }.join.chomp,
+              indented(block, indent),
               "#{indent}# END GENERATED site_cdn #{name}"
             ].join("\n")
           end
         end
+
+        # @param block [String] lines from the left margin
+        # @param indent [String] the indentation to put before each line that is not blank
+        # @return [String] the block indented, without its final newline
+        def indented(block, indent)
+          lines = block.each_line.map { |line| line.strip.empty? ? line : "#{indent}#{line}" }
+          lines.join.chomp
+        end
       end
     end
   end

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

@@ -17,7 +17,7 @@ module Hecks
         # One command that declares a role.
         #
         # @!attribute [r] verb
-        #   @return [String] the command as a host is asked to run it, `Chapter::Aggregate.Command`
+        #   @return [String] the command as a host is asked to run it, `Bluebook::Aggregate.Command`
         # @!attribute [r] role
         #   @return [String] the role the command declares
         # @!attribute [r] arguments
@@ -33,17 +33,17 @@ module Hecks
         # @param registry [Runtime::Registry] the registry a project booted into
         # @return [Array<Check>] every command that declares a role, in the order declared
         def self.checks(registry)
-          registry.bluebooks.values.flat_map do |chapter|
-            chapter.aggregates.flat_map do |aggregate|
-              aggregate.commands.select(&:role).map { |command| check_for(chapter, aggregate, command) }
+          registry.bluebooks.values.flat_map do |declaration|
+            declaration.aggregates.flat_map do |aggregate|
+              aggregate.commands.select(&:role).map { |command| check_for(declaration, aggregate, command) }
             end
           end
         end
 
         # @return [Check] the check for one command that declares a role
-        def self.check_for(chapter, aggregate, command)
-          Check.new(verb: "#{chapter.name}::#{aggregate.hecks_name}.#{command.hecks_name}", role: command.role,
-                    arguments: Bluebook::Synthesizer.args_for(chapter, aggregate, command))
+        def self.check_for(declaration, aggregate, command)
+          Check.new(verb: "#{declaration.name}::#{aggregate.hecks_name}.#{command.hecks_name}", role: command.role,
+                    arguments: Bluebook::Synthesizer.args_for(declaration, aggregate, command))
         end
 
         # Whether the host refused the synthesized arguments themselves, so the role gate was never

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

@@ -25,12 +25,12 @@ module Hecks
           @many = many
         end
 
-        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table
         # @return [Array<Hash{Symbol => Object}>] each checked row, defaults filled; empty when the
-        #   chapter declares none
+        #   bluebook declares none
         # @raise [Table::Invalid] when a row is refused
-        def read(chapter)
-          members = Table.rows_of(chapter, @object)
+        def read(declaration)
+          members = Table.rows_of(declaration, @object)
           problems = []
           problems << "a project declares one #{@object} row, not #{members.size}" if members.size > 1 && !@many
           rows = members.each_with_index.map { |member, index| check(member, index, problems) }

data/lib/hecks/projections/site/routes_ts/listings.rb

@@ -7,6 +7,12 @@ module Hecks
         # The lists `routes.ts` derives from the rows for search engines and the content system:
         # the sitemap and robots paths, and the content-system sources that name a page.
         module Listings
+          # A path segment that is a parameter or a wildcard, where a robots prefix stops.
+          PARAMETER_START = /\A[:*]/
+
+          # A source the content system holds: a `global:` or a `collection:`.
+          CMS_SOURCE = /\A(global|collection):/
+
           module_function
 
           def search(rows)
@@ -24,7 +30,8 @@ module Hecks
           end
 
           def sitemap_paths(rows)
-            RoutesTs.live(rows).select { |row| row.indexable && !row.path.match?(/[:*]/) }.map(&:path).sort
+            live = RoutesTs.live(rows)
+            live.select { |row| row.indexable && !row.path.match?(Table::PARAMETER_OR_WILDCARD) }.map(&:path).sort
           end
 
           def hidden_paths(rows)
@@ -39,7 +46,7 @@ module Hecks
           end
 
           def robots_prefix(path)
-            head = path.split("/").take_while { |part| !part.match?(/\A[:*]/) }.join("/")
+            head = path.split("/").take_while { |part| !part.match?(PARAMETER_START) }.join("/")
             head == path ? path : "#{head}/"
           end
 
@@ -60,13 +67,13 @@ module Hecks
           end
 
           def previews(rows)
-            rows.select { |row| row.source.match?(/\A(global|collection):/) }
-                .to_h { |row| [row.source, { path: row.path, draft: row.preview == "draft" }] }.sort.to_h
+            sourced = rows.select { |row| row.source.match?(CMS_SOURCE) }
+            sourced.to_h { |row| [row.source, { path: row.path, draft: row.preview == "draft" }] }.sort.to_h
           end
 
           def sourced(rows, prefix)
-            rows.select { |row| row.source.start_with?(prefix) }
-                .to_h { |row| [row.source.delete_prefix(prefix), yield(row)] }.sort.to_h
+            named = rows.select { |row| row.source.start_with?(prefix) }
+            named.to_h { |row| [row.source.delete_prefix(prefix), yield(row)] }.sort.to_h
           end
         end
       end

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

@@ -35,13 +35,16 @@ module Hecks
         # The URL prefix under which a draft preview is served.
         PREVIEW_PREFIX = "/admin-preview"
 
+        # A key TypeScript takes bare: a JavaScript identifier.
+        IDENTIFIER = /\A[A-Za-z_$][\w$]*\z/
+
         module_function
 
         # Renders `routes.ts` for a route table.
         #
-        # @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}] `:registry` (Runtime::Registry) the project booted
-        #   into, which holds the Site chapter; `:table` (Table) a table already read, instead
+        #   into, which holds the Site bluebook; `:table` (Table) a table already read, instead
         # @return [Hash{String => String}] `"routes.ts"` to its text
         # @raise [Table::Invalid] when the table is refused
         def call(bluebook:, options: {})
@@ -151,7 +154,7 @@ module Hecks
         end
 
         def key_literal(key)
-          key.to_s.match?(/\A[A-Za-z_$][\w$]*\z/) ? key.to_s : JSON.generate(key.to_s)
+          key.to_s.match?(IDENTIFIER) ? key.to_s : JSON.generate(key.to_s)
         end
       end
     end

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

@@ -29,7 +29,7 @@ module Hecks
 
         # Renders `admin.ts` for a project that declares an admin row.
         #
-        # @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}] `:admin` (Admin) the checked admin row, or nil;
         #   `:extension` (String) the extension the routes module is written with, `ts` by default
         # @return [Hash{String => String}] `"admin.ts"` to its text; empty with no admin row

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

@@ -24,10 +24,11 @@ module Hecks
 
         module_function
 
-        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table and the edge
+        # @param bluebook [Bluebook::Declaration] the bluebook that declares the route table and the
+        #   edge
         # @param options [Hash{Symbol => Object}] `:registry` (Runtime::Registry) the project booted
         #   into; or `:table` (Table) and `:edge` (Edge), already read
-        # @return [Hash{String => String}] each region's name to its text; empty when the chapter
+        # @return [Hash{String => String}] each region's name to its text; empty when the bluebook
         #   declares no edge, and without `"listener_rules"` when the edge has no load balancer
         # @raise [Table::Invalid] when the table or the edge is refused
         def call(bluebook:, options: {})