hecks 4.0.0 → 6.0.0

data/lib/hecks/projections/model.rb

@@ -10,6 +10,9 @@ module Hecks
 
       projects_as :model, declares: "Bluebook", emits: :files
 
+      # One comment line's worth of prose: up to 62 characters ending at a space or the end.
+      COMMENT_LINE = /.{1,62}(?:\s|$)/
+
       # Per-construct Ruby facts the grammar does not state (defaults, coercion, class shape).
       HOST = {
         "Policy" => {
@@ -36,7 +39,7 @@ module Hecks
 
       # Renders every `HOST`-listed construct's holding half.
       #
-      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter itself (the language
+      # @param bluebook [Bluebook::Declaration] the "Bluebook" bluebook itself (the language
       #   describing its own constructs), not a domain being projected
       # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
       #   `Projector::Target` calling convention
@@ -49,7 +52,7 @@ module Hecks
       # Renders one construct's class: emission, readers and constructor, wrapped in
       # the generated-file header and namespace.
       #
-      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
+      # @param bluebook [Bluebook::Declaration] the "Bluebook" bluebook the construct's own
       #   attributes are read from
       # @param name [String] the construct's name, a key into `HOST` (`"Policy"`, ...)
       # @param host [Hash{Symbol => Object}] `name`'s `HOST` entry
@@ -81,7 +84,7 @@ module Hecks
       # Renders the `emits_ir` call. A computed field (Deviations::COMPUTED) rides after the
       # declared ones and needs a `renders` entry, since there is nothing to `send`.
       #
-      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
+      # @param bluebook [Bluebook::Declaration] the "Bluebook" bluebook the construct's own
       #   attributes are read from
       # @param name [String] the construct's name, a key into `HOST`
       # @return [String] the rendered `emits_ir(...)` call, one field per line
@@ -96,14 +99,15 @@ module Hecks
       # What the construct emits: the declared attributes less every `Deviations` entry.
       # spec/model_shape_conformance_spec computes it from the same tables.
       #
-      # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
+      # @param bluebook [Bluebook::Declaration] the "Bluebook" bluebook the construct's own
       #   attributes are read from
       # @param name [String] the construct's name, an aggregate on `bluebook`
       # @return [Array<Symbol>] the declared attribute names, minus every field
       #   `Deviations` marks as parent-ref, judge-only, off-the-wire, dynamic-tail,
       #   folded, or unpacked
       def emitted_fields(bluebook, name)
-        declared = bluebook.aggregate(name).attributes.map(&:name).reject { |f| Deviations.parent_ref?(f) }
+        attributes = bluebook.aggregate(name).attributes
+        declared = attributes.map(&:name).reject { |f| Deviations.parent_ref?(f) }
         declared - omitted_fields(name)
       end
 
@@ -165,7 +169,7 @@ module Hecks
       #
       # @param text [String] the prose to wrap
       # @return [String] the wrapped text, its lines joined by `"\n# "`
-      def wrap(text) = text.scan(/.{1,62}(?:\s|$)/).map(&:strip).join("\n# ")
+      def wrap(text) = text.scan(COMMENT_LINE).map(&:strip).join("\n# ")
     end
   end
 end

data/lib/hecks/projections/oidc.rb

@@ -15,12 +15,15 @@ module Hecks
 
       projects_as :oidc
 
+      # An empty JSON list spread over lines, `[\n\n]`, as some json releases print it.
+      SPREAD_EMPTY_LIST = /\[\n\s*\]/
+
       module_function
 
       # Projects the manifest; `audience:` overrides the domain name (an IdP audience is
       # usually a URL).
       #
-      # @param bluebook [Bluebook::Chapter] the chapter being projected
+      # @param bluebook [Bluebook::Declaration] the bluebook being projected
       # @param options [Hash{Symbol => Object}] `:audience` (String, Symbol, nil)
       #   overrides the manifest's `"audience"` value
       # @return [Hash{String => Object}] `"audience"` (String), `"scopes"` (see
@@ -32,10 +35,16 @@ module Hecks
         {
           "audience" => (options[:audience] || bluebook.name).to_s,
           "scopes"   => scopes,
-          "roles"    => scopes.map { |scope| scope["role"] }.compact.uniq.sort
+          "roles"    => declared_roles(scopes)
         }
       end
 
+      # Every distinct role the scopes demand, sorted; a scope with no role adds none.
+      def declared_roles(scopes)
+        roles = scopes.flat_map { |scope| scope["roles"] || [scope["role"]] }.compact
+        roles.uniq.sort
+      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
@@ -44,13 +53,13 @@ module Hecks
       # @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"
+        "#{JSON.pretty_generate(manifest).gsub(SPREAD_EMPTY_LIST, "[]")}\n"
       end
 
       # Every command's scope entry, entity commands included (they dispatch as `Entity.Command`).
       # Sorted by scope so two manifest versions diff cleanly.
       #
-      # @param bluebook [Bluebook::Chapter] the chapter being projected
+      # @param bluebook [Bluebook::Declaration] the bluebook being projected
       # @return [Array<Hash{String => Object}>] every command's scope entry (see
       #   `command_scopes`), sorted by `"scope"`
       def scopes_for(bluebook)
@@ -60,7 +69,7 @@ module Hecks
 
       # Projects one aggregate's own commands and every entity nested inside it.
       #
-      # @param bluebook [Bluebook::Chapter] the aggregate's owning chapter, for the
+      # @param bluebook [Bluebook::Declaration] the aggregate's owning bluebook, for the
       #   verb and scope prefixes
       # @param aggregate [Bluebook::Aggregate] the aggregate being projected
       # @return [Array<Hash{String => Object}>] the aggregate's and its entities'
@@ -100,14 +109,17 @@ module Hecks
       #   scope prefix
       # @return [Array<Hash{String => Object}>] one entry per command: `"scope"`
       #   (String), `"verb"` (String), `"role"` (String, `nil` if the command
-      #   declares none)
+      #   declares none), and `"roles"` (every role) when it declares several
       def command_scopes(commands, verb_prefix, scope_prefix)
         commands.map do |command|
-          {
+          entry = {
             "scope" => "#{scope_prefix}.#{Naming.snake(command.hecks_name)}",
             "verb"  => "#{verb_prefix}.#{command.hecks_name}",
             "role"  => command.role
           }
+          # Only a command run by several roles says so, so every other manifest reads as it did.
+          entry["roles"] = command.roles if command.roles.size > 1
+          entry
         end
       end
     end

data/lib/hecks/projections/parser_table.rb

@@ -2,7 +2,7 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # The Rust parser's keyword table, projected from the chapter's own Syntax aggregate,
+    # The Rust parser's keyword table, projected from the bluebook's own Syntax aggregate,
     # so the parser's grammar knowledge is derived rather than hand-typed a second time.
     module ParserTable
       extend Projector::Target
@@ -10,9 +10,9 @@ module Hecks
 
       module_function
 
-      # Projects the Rust parser's keyword and closed-set tables for one chapter.
+      # Projects the Rust parser's keyword and closed-set tables for one bluebook.
       #
-      # @param bluebook [Bluebook::Chapter] the chapter to project; the language's own
+      # @param bluebook [Bluebook::Declaration] the bluebook to project; the language's own
       #   for the ordinary `hecks project_parser_table` run
       # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
       #   `Projector::Target` calling convention
@@ -21,18 +21,18 @@ module Hecks
 
       module_function
 
-      # The chapter's `Syntax` aggregate. Taken from the argument, not the grammar registry,
-      # so the projection is not pinned to the language's own chapter.
+      # The bluebook's `Syntax` aggregate. Taken from the argument, not the grammar registry,
+      # so the projection is not pinned to the language's own bluebook.
       #
-      # @param bluebook [Bluebook::Chapter] the chapter to read the Syntax aggregate
+      # @param bluebook [Bluebook::Declaration] the bluebook to read the Syntax aggregate
       #   from
-      # @return [Bluebook::Aggregate, nil] the chapter's `"Syntax"` aggregate, `nil` if
+      # @return [Bluebook::Aggregate, nil] the bluebook's `"Syntax"` aggregate, `nil` if
       #   it declares none
       def syntax(bluebook) = bluebook.aggregate("Syntax")
 
       # Every cell as text, as spec/syntax_conformance_spec.rb's `rows` helper reads it.
       #
-      # @param bluebook [Bluebook::Chapter] the chapter to read from
+      # @param bluebook [Bluebook::Declaration] the bluebook to read from
       # @param name [String] the closed-set value object's name, such as `"Context"`
       # @return [Array<Hash{Symbol => String}>] one row per declared member, every
       #   field stringified
@@ -43,7 +43,7 @@ module Hecks
 
       # Reads one closed set's member names, for a Rust `&[&str]` constant.
       #
-      # @param bluebook [Bluebook::Chapter] the chapter to read from
+      # @param bluebook [Bluebook::Declaration] the bluebook to read from
       # @param name [String] the closed-set value object's name
       # @return [Array<String>] every declared member's `:name` field
       def closed_set_members(bluebook, name) = rows(bluebook, name).map { |row| row[:name] }
@@ -90,7 +90,7 @@ module Hecks
       # Renders the whole Rust source. Keyword and Argument rows come from `SyntaxBoot.call`,
       # which dispatches the seed rows so `status` is a real lifecycle (ADR 0026).
       #
-      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @param bluebook [Bluebook::Declaration] the bluebook to project
       # @return [String] the rendered `KEYWORDS`/`ARGUMENTS`/closed-set Rust source
       def render(bluebook)
         table     = Hecks::Bluebook::MetaValidator::SyntaxBoot.call

data/lib/hecks/projections/phrase_table.rb

@@ -0,0 +1,105 @@
+require_relative "../projector"
+require_relative "parser_table"
+
+module Hecks
+  module Projections
+    # The Rust parser's sentence table, projected from the Sentence bluebook's `PhraseSeed` rows, so
+    # what an author may write in plain sentences is a table rather than code typed a second time.
+    module PhraseTable
+      extend Projector::Target
+
+      projects_as :phrase_table, declares: "Phrase"
+
+      # The bluebook the rows are declared in, read from the language's own tree.
+      SENTENCE_FILE = File.expand_path("../language/sentence/sentence.bluebook", __dir__)
+
+      # The ports and adapters a bare bluebook needs loaded before its predicates can be recovered.
+      SUPPORT_FILES = %w[ports/persistence.port ports/extraction.port
+                         adapters/driven/memory.adapter adapters/driven/prism.adapter]
+                      .map { |path| File.expand_path("../#{path}", __dir__) }.freeze
+
+      # The columns of a `PhraseRow`, in the order the Rust struct declares them.
+      FIELDS = %i[id context pattern opens canonical status].freeze
+
+      module_function
+
+      # @param bluebook [Bluebook::Declaration] the Sentence bluebook
+      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @return [String] the rendered Rust source
+      def call(bluebook:, options: {}) = render(bluebook)
+
+      # Loads the Sentence bluebook on its own, in a registry of its own.
+      #
+      # @return [Bluebook::Declaration] the bluebook declared by `SENTENCE_FILE`
+      def declaration
+        registry = Hecks::Runtime::Registry.new
+        Hecks.with_registry(registry) { (SUPPORT_FILES + [SENTENCE_FILE]).each { |file| Kernel.load(file) } }
+        registry.bluebook("Sentence")
+      end
+
+      # @param bluebook [Bluebook::Declaration] the Sentence bluebook
+      # @return [Array<Hash{Symbol => String}>] one row per declared phrase, every field a string
+      #   and an omitted column read as its default
+      def rows(bluebook)
+        seed = bluebook.aggregate("Phrase").value_objects.find { |vo| vo.hecks_name == "PhraseSeed" }
+        seed.members.map do |member|
+          row = member.to_h.transform_values(&:to_s)
+          FIELDS.to_h { |field| [field, row.fetch(field) { default(field) }] }
+        end
+      end
+
+      # @param field [Symbol] a `FIELDS` member a row left out
+      # @return [String] the column's default
+      def default(field) = { canonical: "yes", status: "admitted" }.fetch(field, "")
+
+      # @param row [Hash{Symbol => String}] one phrase, keyed by `FIELDS`
+      # @return [String] one `PhraseRow { ... },` line
+      def phrase_row(row)
+        fields = FIELDS.map { |field| "#{field}: #{ParserTable.rust_string(row[field])}" }
+        "    PhraseRow { #{fields.join(", ")} },"
+      end
+
+      # @param bluebook [Bluebook::Declaration] the Sentence bluebook
+      # @return [String] the whole `phrases.rs`
+      def render(bluebook)
+        <<~RUST
+          // GENERATED by hecks project_phrase_table from the Sentence bluebook's PhraseSeed rows
+          // (lib/hecks/language/sentence/sentence.bluebook) — DO NOT EDIT BY HAND.
+          //
+          // Re-run `hecks project_phrase_table` after any phrase change. The drift spec
+          // (spec/phrase_table_spec.rb) fails the normal suite when this file goes stale.
+
+          /// One sentence an author may write.
+          #[derive(Debug, Clone, Copy)]
+          pub struct PhraseRow {
+              /// The phrase's name, which the sentence front end lowers by.
+              pub id: &'static str,
+              /// The block it is legal in: File, Domain, Aggregate, Has, ValueObject, Lifecycle,
+              /// Command, Query or Condition for a domain; ExamplesFile, Examples, Background,
+              /// Example, Step or Outcome for an examples file.
+              pub context: &'static str,
+              /// Literal words, `(a|an)` alternatives and `{slot:kind}` fill-ins.
+              pub pattern: &'static str,
+              /// The block this sentence opens, or "" for a plain line.
+              pub opens: &'static str,
+              /// "yes" for the one spelling the formatter writes.
+              pub canonical: &'static str,
+              pub status: &'static str,
+          }
+
+          impl PhraseRow {
+              /// A retired phrase is refused like any unknown sentence.
+              pub fn live(&self) -> bool {
+                  matches!(self.status, "" | "admitted" | "deprecated")
+              }
+          }
+
+          pub static PHRASES: &[PhraseRow] = &[
+          #{rows(bluebook).map { |row| phrase_row(row) }.join("\n")}
+          ];
+        RUST
+      end
+    end
+  end
+end

data/lib/hecks/projections/plain_english.rb

@@ -26,6 +26,15 @@ module Hecks
         "login" => "logging in", "logout" => "logging out", "payout" => "paying out"
       }.freeze
 
+      # A word of two or more capitals, spoken as an acronym: "ATM".
+      ACRONYM = /\A[A-Z]{2,}\z/
+      # The lowercase letter a text opens with.
+      LEADING_LOWER = /\A[[:lower:]]/
+      # A verb ending in a silent "e" after a consonant: "purchase", "make".
+      SILENT_E = /[^aeiouy]e\z/
+      # A one-syllable verb closed by one plain consonant after one vowel: "log", "set".
+      SHORT_CLOSED = /\A[^aeiou]*[aeiou][bdgklmnprt]\z/
+
       module_function
 
       # A construct name as a lowercase noun phrase; acronyms keep their capitals.
@@ -33,7 +42,8 @@ module Hecks
       # @param name [String, Symbol] a construct or field name, such as `ATMCard` or `daily_limit`
       # @return [String] the spoken noun, such as "ATM card" or "daily limit"
       def noun(name)
-        Naming.words(name).split.map { |word| word.match?(/\A[A-Z]{2,}\z/) ? word : word.downcase }.join(" ")
+        words = Naming.words(name).split
+        words.map { |word| word.match?(ACRONYM) ? word : word.downcase }.join(" ")
       end
 
       # @param phrase [String] a spoken noun phrase
@@ -56,7 +66,7 @@ module Hecks
 
       # @param text [String] a sentence fragment
       # @return [String] the fragment with its first letter capitalised
-      def upper(text) = text.sub(/\A[[:lower:]]/, &:upcase)
+      def upper(text) = text.sub(LEADING_LOWER, &:upcase)
 
       # A command as the act of doing it. A one-word command takes its holder as the object;
       # a command named as a past state ("Debited") reads as marking the holder so.
@@ -84,14 +94,14 @@ module Hecks
       def gerund(verb)
         return PHRASAL[verb] if PHRASAL.key?(verb)
         return "#{verb[0..-3]}ying" if verb.end_with?("ie")
-        return "#{verb[0..-2]}ing" if verb.match?(/[^aeiouy]e\z/) || verb.end_with?("ue")
+        return "#{verb[0..-2]}ing" if verb.match?(SILENT_E) || verb.end_with?("ue")
         return "#{verb}#{verb[-1]}ing" if doubles?(verb)
 
         "#{verb}ing"
       end
 
       # One vowel then one plain consonant ("log", "set") doubles; so do the stressed `DOUBLED`.
-      def doubles?(verb) = DOUBLED.include?(verb) || verb.match?(/\A[^aeiou]*[aeiou][bdgklmnprt]\z/)
+      def doubles?(verb) = DOUBLED.include?(verb) || verb.match?(SHORT_CLOSED)
     end
   end
 end

data/lib/hecks/projections/rails_app.rb

@@ -0,0 +1,77 @@
+require_relative "../projector"
+require_relative "../naming"
+require_relative "site/table"
+
+module Hecks
+  module Projections
+    # A bluebook projected as the files a Rails app needs to drive it through `hecks-rails`: a
+    # controller per aggregate, and a routes file with a `resources` line for each.
+    #
+    #   Projector.call(:rails_app, bluebook: bluebook)
+    #   # => { "app/controllers/accounts_controller.rb" => "...", "config/routes.rb" => "..." }
+    #
+    # A model needs no file: `hecks-rails` generates one per aggregate at boot, so one is written by
+    # hand only to hold presentation methods. A controller joins the domain by its name and the
+    # `resources` line draws a show and a POST per command, so neither file names more than that.
+    # The text only names `hecks-rails`'s conventions; nothing here requires Rails.
+    module RailsApp
+      extend Projector::Target
+
+      projects_as :rails_app, emits: :files
+
+      module_function
+
+      # Projects every file the app needs for a bluebook.
+      #
+      # @param bluebook [Bluebook::Declaration] the bluebook the app drives
+      # @param options [Hash] the registry's call shape
+      # @option options [Array<Bluebook::Declaration>] :route_bluebooks every bluebook the routes
+      #   file
+      #   draws, when the app drives more than this one; this bluebook alone when absent
+      # @return [Hash{String => String}] each file's path in the app to its text
+      def call(bluebook:, options: {})
+        controllers = driven(bluebook).to_h { |aggregate| controller(aggregate) }
+        controllers.merge("config/routes.rb" => routes(options[:route_bluebooks] || [bluebook]))
+      end
+
+      # @param bluebook [Bluebook::Declaration] a bluebook
+      # @return [Array<Bluebook::Aggregate>] its aggregates that take commands; one that only holds
+      #   rows, such as an `App` row, has no page
+      def driven(declaration) = declaration.aggregates.select { |aggregate| aggregate.commands.any? }
+
+      # @param aggregate [Bluebook::Aggregate] the aggregate
+      # @return [Array(String, String)] the controller's path and text
+      def controller(aggregate)
+        name = "#{Naming.pascal(Naming.plural(Naming.snake(aggregate.hecks_name)))}Controller"
+        ["app/controllers/#{Naming.snake(name)}.rb",
+         "# Joins the domain by its name; redefine an action here and call `super` to keep the generated one.\n" \
+         "class #{name} < ApplicationController\nend\n"]
+      end
+
+      # @param bluebooks [Array<Bluebook::Declaration>] the bluebooks to draw
+      # @return [String] the routes file's text
+      def routes(declarations)
+        resources = resources_of(declarations)
+        drawn = ["  root to: \"#{home(declarations, resources)}#index\"", *resources.map { |_, name| "  resources :#{name}" }]
+        "# A list, a show and a POST per command, drawn from the domain by hecks-rails.\n" \
+          "Rails.application.routes.draw do\n#{drawn.join("\n")}\nend\n"
+      end
+
+      # @param bluebooks [Array<Bluebook::Declaration>] the bluebooks to draw
+      # @return [Array<Array(String, String)>] each driven aggregate's name and resource name
+      def resources_of(declarations)
+        aggregates = declarations.flat_map { |declaration| driven(declaration) }
+        aggregates.map { |aggregate| [aggregate.hecks_name, Naming.plural(Naming.snake(aggregate.hecks_name))] }
+      end
+
+      # @param bluebooks [Array<Bluebook::Declaration>] the bluebooks to draw
+      # @param resources [Array<Array(String, String)>] each aggregate's name and resource name
+      # @return [String] the resource the root path lists: the `App` row's home, else the first
+      def home(declarations, resources)
+        rows = declarations.flat_map { |declaration| Site::Table.rows_of(declaration, "App") }
+        named = rows.filter_map { |row| row[:home] }.first
+        resources.find { |name, _| name == named }&.last || resources.first.last
+      end
+    end
+  end
+end

data/lib/hecks/projections/reference.rb

@@ -8,7 +8,7 @@ module Hecks
   end
 
   module Projections
-    # The DSL reference pages, projected from the chapter's Syntax aggregate;
+    # The DSL reference pages, projected from the bluebook's Syntax aggregate;
     # tables come from the declaration, prose is preserved from what's already committed.
     module Reference
       extend Projector::Target
@@ -20,7 +20,7 @@ module Hecks
       # Renders one reference page per DSL keyword context, carrying prose
       # over from whatever is already committed under `options[:from]`.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook declaring the
       #   Syntax aggregate to render pages from; unused beyond admission, since the
       #   keyword table this reads comes from the global `Syntax` grammar
       # @param options [Hash] must include `:from`

data/lib/hecks/projections/rust_vocabulary/arguments.rb

@@ -35,7 +35,7 @@ module Hecks
         def site_specs(row, grouped)
           key   = site_key(row)
           specs = grouped.fetch(key, [])
-          wants = row.fetch("template").scan(/\{(\w+)\}/).flatten.uniq
+          wants = RustVocabulary.placeholders(row.fetch("template"))
           names = specs.map { |spec| spec.fetch("argument") }
           unless names == wants
             raise ArgumentError, "RefusalSiteArgument for #{key.join("/")} declares #{names.inspect}; " \

data/lib/hecks/projections/rust_vocabulary/tables.rb

@@ -0,0 +1,20 @@
+module Hecks
+  module Projections
+    module RustVocabulary
+      # Table name => enum name, variant-naming fields, file stem and kind.
+      # `:order` adds `position`; `:templates` adds `render` and the typed `<Variant>Args`.
+      TABLES = {
+        "RefusalTemplate"        => { enum: "RefusalSite",     variant_from: %w[refusal site], file: "refusal_template",
+                                      kind: :templates, arguments: "RefusalSiteArgument" },
+        "QueryComparator"        => { enum: "QueryComparator", variant_from: %w[name], file: "query_comparator", kind: :set },
+        "FieldHint"              => { enum: "FieldHint",       variant_from: %w[name], file: "field_hint", kind: :set },
+        "RefusalClass"           => { enum: "RefusalClass",    variant_from: %w[name], file: "refusal_class", kind: :set },
+        "Reducer"                => { enum: "Reducer",         variant_from: %w[name], file: "reducer", kind: :set },
+        "AggregateDispatchOrder" => { enum: "AggregateStep",   variant_from: %w[step], file: "aggregate_dispatch_order",
+                                      kind: :order },
+        "EntityDispatchOrder"    => { enum: "EntityStep",      variant_from: %w[step], file: "entity_dispatch_order",
+                                      kind: :order }
+      }.freeze
+    end
+  end
+end

data/lib/hecks/projections/rust_vocabulary.rb

@@ -6,13 +6,14 @@ require_relative "vocabulary"
 require_relative "rust_vocabulary/enum_body"
 require_relative "rust_vocabulary/arguments"
 require_relative "rust_vocabulary/tests"
+require_relative "rust_vocabulary/tables"
 
 module Hecks
   module Projections
     # The language's closed sets as Rust enums, one `rust/src/kernel/vocab/<table>.rs` per table,
     # matched with no wildcard arm so a new row fails to compile until it is handled.
     #
-    #   Projector.call(:rust_vocabulary, bluebook: <the Bluebook chapter>)
+    #   Projector.call(:rust_vocabulary, bluebook: <the Bluebook bluebook>)
     #   # => { "vocab/mod.rs" => "...", "vocab/refusal_template.rs" => "...", ... }
     module RustVocabulary
       extend Projector::Target
@@ -22,18 +23,10 @@ module Hecks
       GENERATOR = "hecks project_rust_vocabulary".freeze
       SOURCE    = "lib/hecks/language/bluebook/vocabulary.bluebook".freeze
 
-      # Table name => enum name, variant-naming fields, file stem and kind.
-      # `:order` adds `position`; `:templates` adds `render` and the typed `<Variant>Args`.
-      TABLES = {
-        "RefusalTemplate"        => { enum: "RefusalSite",     variant_from: %w[refusal site], file: "refusal_template",
-                                      kind: :templates, arguments: "RefusalSiteArgument" },
-        "QueryComparator"        => { enum: "QueryComparator", variant_from: %w[name], file: "query_comparator", kind: :set },
-        "FieldHint"              => { enum: "FieldHint",       variant_from: %w[name], file: "field_hint", kind: :set },
-        "AggregateDispatchOrder" => { enum: "AggregateStep",   variant_from: %w[step], file: "aggregate_dispatch_order",
-                                      kind: :order },
-        "EntityDispatchOrder"    => { enum: "EntityStep",      variant_from: %w[step], file: "entity_dispatch_order",
-                                      kind: :order }
-      }.freeze
+      # A name Rust accepts as an enum variant: a capital, then letters and digits.
+      VARIANT_NAME = /\A[A-Z][A-Za-z0-9]*\z/
+      # A `{name}` placeholder in a refusal template, capturing the name.
+      PLACEHOLDER = /\{(\w+)\}/
 
       # Keywords Rust refuses as a raw identifier, so they cannot take the `r#` escape.
       NOT_RAW = %w[crate self Self super].freeze
@@ -49,6 +42,10 @@ module Hecks
         Hecks::Vocabulary.fetch("RustReservedWord").include?(name) ? "r##{name}" : name
       end
 
+      # @param template [String] a refusal template
+      # @return [Array<String>] its placeholder names, each once, in first-appearance order
+      def placeholders(template) = template.scan(PLACEHOLDER).flatten.uniq
+
       def call(bluebook:, options: {}) = render(bluebook)
 
       def render(bluebook)
@@ -121,8 +118,7 @@ module Hecks
         ["#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]",
          "pub enum #{enum} {",
          variants.map { |variant| "    #{variant}," },
-         "}",
-         ""]
+         "}", ""]
       end
 
       def name_field(kind) = kind == :order ? "step" : "name"
@@ -132,14 +128,15 @@ module Hecks
 
       def variant_name(row, fields)
         name = fields.map { |field| Naming.pascal(row.fetch(field)) }.join
-        raise ArgumentError, "#{name.inspect} is not a Rust variant name" unless name.match?(/\A[A-Z][A-Za-z0-9]*\z/)
+        raise ArgumentError, "#{name.inspect} is not a Rust variant name" unless name.match?(VARIANT_NAME)
 
         name
       end
 
       # Only `\`, `"` and newlines need escaping in the text a vocabulary row holds.
       def rust_string(text)
-        escaped = text.to_s.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("\n") { "\\n" }
+        source = text.to_s
+        escaped = source.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }.gsub("\n") { "\\n" }
         "\"#{escaped}\""
       end
     end

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

@@ -9,7 +9,7 @@ module Hecks
       # the host that vouches for it, the roles that count as an admin, and the two routes the
       # sign-in is built from.
       #
-      # A project declares one `member` row of a `value_object "Admin"` in the chapter that holds
+      # A project declares one `member` row of a `value_object "Admin"` in the bluebook that holds
       # its route table. `docs/site-routes.md` lists the fields. A project that declares none has
       # no admin sign-in to project.
       class Admin
@@ -45,14 +45,14 @@ module Hecks
         # @return [Setting] the checked row, defaults filled
         attr_reader :setting
 
-        # Reads and checks the admin row a chapter declares.
+        # Reads and checks the admin row 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
-        # @return [Admin, nil] the checked setting, or nil when the chapter declares none
+        # @return [Admin, nil] the checked setting, or nil when the bluebook declares none
         # @raise [Table::Invalid] when the row is refused or contradicts the routes
-        def self.read(chapter, table:)
-          members = Table.rows_of(chapter, OBJECT)
+        def self.read(declaration, table:)
+          members = Table.rows_of(declaration, OBJECT)
           return nil if members.empty?
 
           new(members, table: table)
@@ -74,7 +74,7 @@ module Hecks
         end
 
         # @return [Array<String>] the roles that count as an admin
-        def roles = setting.roles.split(",").map(&:strip).reject(&:empty?)
+        def roles = Hecks::Text.comma_list(setting.roles)
 
         # @return [String] the path of the content system's sign-in endpoint inside its own API, the
         #   part of `sso_target` after `<cms_base>/api`

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

@@ -30,7 +30,7 @@ module Hecks
 
         # Renders the four files 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
         # @return [Hash{String => String}] each file's relative path to its text; empty with no row
         def call(bluebook:, options: {})

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

@@ -29,6 +29,9 @@ module Hecks
           # An invariant that holds unless the kind is the named one: what the rest of it reads.
           GUARD = /\A(\w+)(?:\.value)? != "([^"]+)" \|\| (.*)\z/m
 
+          # A double-quoted string, capturing the text between the quotes.
+          QUOTED = /"([^"]+)"/
+
           # A limit written as a size comparison.
           LIMIT = /\A(\w+)\.size <= (\d+)\z/
 
@@ -72,7 +75,7 @@ module Hecks
           # @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]
+            found && [found[2], found[1].scan(QUOTED).flatten]
           end
 
           # @return [Array<MatchData>] the invariants that restrict a part to a literal list
@@ -99,7 +102,7 @@ module Hecks
               object.members.all? { |row| kinds.include?(row[:kind].to_s) }
           end
 
-          def words(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+          def words(text) = Hecks::Text.comma_list(text)
 
           # @return [Hash{String => Array<String>}] the slots each kind's guarded invariants read
           def mentions(item, name, kinds)