hecks 3.13.0 → 4.0.0

data/lib/hecks/projections/glossary/sentences/queries.rb

@@ -0,0 +1,90 @@
+require_relative "../../plain_english"
+require_relative "paths"
+
+module Hecks
+  module Projections
+    module Glossary
+      module Sentences
+        # The sentence a list's term carries, read from its filters, ordering and limit:
+        # "Orders that are available, sorted by pizza name, A to Z."
+        module Queries
+          # How each comparison is said between a field and its value.
+          OPERATORS = {
+            "eq" => "is", "ne" => "is not", "lt" => "is less than", "lte" => "is at most",
+            "gt" => "is more than", "gte" => "is at least", "in" => "is", "contains" => "includes"
+          }.freeze
+
+          module_function
+
+          # @param query [Bluebook::Query] the query
+          # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct it lists
+          # @param value_objects [Array<Bluebook::ValueObject>] the aggregate's value objects
+          # @return [Array<String>] the author's description, when there is one, then the
+          #   derived sentence
+          def paragraphs(query, holder, value_objects)
+            paths = Paths.new(holder, value_objects)
+            [query.description, sentence(query, holder, paths), limit(query)].compact
+          end
+
+          def sentence(query, holder, paths)
+            things = PlainEnglish.plural(PlainEnglish.noun(holder.hecks_name))
+            filters = query.wheres.map { |clause| filter(clause, paths) }
+            subject = filters.empty? ? "All #{things}" : "#{PlainEnglish.upper(things)} #{filters.join(" and ")}"
+            "#{subject}#{order(query, things, paths)}."
+          end
+
+          # "that are available" on the lifecycle field, otherwise "whose price is less than ...".
+          def filter(clause, paths)
+            operator = clause.op.to_s
+            value = value_words(clause.value, operator)
+            return "that are #{"not " if operator == "ne"}#{value}" if paths.lifecycle?(clause.field)
+            return "that have none #{value}" if operator == "none_in_state"
+
+            "whose #{paths.label(clause.field)} #{OPERATORS.fetch(operator, operator.tr("_", " "))} #{value}"
+          end
+
+          # A parameter is "the ceiling you give"; a list of states is "open or frozen".
+          def value_words(value, operator)
+            return "the #{PlainEnglish.noun(value)} you give" if value.is_a?(Symbol)
+            return PlainEnglish.states(value.to_s.split(",").map(&:strip)) if operator == "in"
+
+            PlainEnglish.state(value)
+          end
+
+          # ", sorted by price, lowest first", and where unset values go when that is declared.
+          def order(query, things, paths)
+            order_by = query.order_by
+            return "" unless order_by
+
+            label = paths.label(order_by.field)
+            words = direction(paths.type(order_by.field), order_by.direction.to_s == "desc")
+            ", sorted by #{label}#{words}#{nulls(query, things, label)}"
+          end
+
+          def direction(type, descending)
+            case type
+            when "String" then descending ? ", Z to A" : ", A to Z"
+            when "Integer", "Float" then descending ? ", highest first" : ", lowest first"
+            else descending ? ", in reverse order" : ""
+            end
+          end
+
+          def nulls(query, things, label)
+            mode = query.null_semantics&.mode.to_s
+            return "" unless %w[first last].include?(mode)
+
+            ", with #{things} that have no #{label} #{mode}"
+          end
+
+          # "Shows at most 50." when the list is capped.
+          def limit(query)
+            value = query.limit&.value
+            return nil unless value
+
+            value.is_a?(Symbol) ? "Shows at most the number you give." : "Shows at most #{value}."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/glossary/sentences/value_objects.rb

@@ -1,6 +1,7 @@
 require_relative "../../../naming"
 require_relative "../../statements"
 require_relative "../sensitivity"
+require_relative "../../../bluebook/named_pattern"
 
 module Hecks
   module Projections
@@ -14,6 +15,13 @@ module Hecks
             "Boolean" => "yes or no", "TrueClass" => "yes or no", "FalseClass" => "yes or no"
           }.freeze
 
+          # What each named pattern asks of a value, in words.
+          PATTERN_WORDS = {
+            present: "must not be blank", not_empty: "must not be empty", no_whitespace: "must have no spaces",
+            snake_name: "must be lowercase words joined by underscores", git_sha: "must be a commit id",
+            digits: "must be digits only"
+          }.freeze
+
           module_function
 
           def paragraphs(value_object, index, within, sensitive = {})
@@ -28,7 +36,7 @@ module Hecks
             attributes = value_object.attributes
             return "A marker with no details of its own." if attributes.empty?
 
-            return "#{Sentences.upper_first(type_words(attributes.first, index, within))}." if bare_value?(attributes)
+            return bare_sentence(attributes.first, index, within) if bare_value?(attributes)
 
             fields = attributes.map { |field| field_phrase(field, index, within, sensitive[field.name.to_s]) }
             "Made up of #{Naming.to_sentence_list(fields)}."
@@ -36,18 +44,37 @@ module Hecks
 
           def bare_value?(attributes) = attributes.size == 1 && attributes.first.name.to_s == "value"
 
-          # "amount (a whole number)", or "medications (text, PHI)" when marked sensitive.
+          # "Text that must not be blank.", or just "A whole number." when nothing constrains it.
+          def bare_sentence(field, index, within)
+            rule = constraint(field)
+            "#{Sentences.upper_first(type_words(field, index, within))}#{" that #{rule}" if rule}."
+          end
+
+          # "amount (a whole number)", "name (text, must not be blank)", or, when marked
+          # sensitive, "medications (text, PHI)".
           def field_phrase(field, index, within, marking = nil)
-            detail = [type_words(field, index, within), (Sensitivity.tag(marking) if marking)].compact.join(", ")
+            detail = [type_words(field, index, within), constraint(field), ("optional" if field.optional?),
+                      (Sensitivity.tag(marking) if marking)].compact.join(", ")
             "#{Naming.words(field.name).downcase} (#{detail})"
           end
 
+          # A plain type in words, a reference as a link to what it points at, otherwise a link
+          # to the value's own term.
           def type_words(field, index, within)
-            type  = field.type.to_s
-            inner = TYPE_WORDS[type] || index.link(:value_object, type, within: within)
+            inner = if field.reference? then index.link(:aggregate, field.type.target_name)
+                    else TYPE_WORDS[field.type.to_s] || index.link(:value_object, field.type.to_s, within: within)
+                    end
             field.list? ? "a list of #{inner}" : inner
           end
 
+          # What a field's pattern asks of its value, or nil when it has none.
+          def constraint(field)
+            return nil unless field.pattern
+
+            name = Bluebook::NamedPattern::TABLE.key(field.pattern)
+            name ? PATTERN_WORDS[name] : "must follow a set format"
+          end
+
           # A multi-field row leads with its first field and keeps the rest beside it,
           # so no row loses what makes it distinct.
           def closed_set_sentence(members)

data/lib/hecks/projections/glossary/sentences.rb

@@ -2,6 +2,8 @@ require_relative "../../naming"
 require_relative "../statements"
 require_relative "sensitivity"
 require_relative "sentences/value_objects"
+require_relative "sentences/actions"
+require_relative "sentences/queries"
 
 module Hecks
   module Projections
@@ -12,8 +14,6 @@ module Hecks
       module Sentences
         # The one sentence each kind of term other than an entity or value object carries.
         SINGLES = {
-          command:    ->(facts, _index) { command_sentence(facts[:command]) },
-          query:      ->(facts, _index) { facts[:query].description },
           event:      ->(facts, index) { event_sentence(facts, index) },
           policy:     ->(facts, index) { policy_sentence(facts[:policy], index) },
           saga:       ->(facts, index) { saga_sentence(facts[:saga], index) },
@@ -28,6 +28,8 @@ module Hecks
           case entry.kind
           when :entity       then holder_paragraphs(facts[:entity])
           when :value_object then value_object_paragraphs(entry, index)
+          when :command      then Actions.paragraphs(facts, index)
+          when :query        then Queries.paragraphs(facts[:query], facts[:holder], facts[:value_objects])
           else [SINGLES.fetch(entry.kind).call(facts, index)]
           end.compact
         end
@@ -67,7 +69,7 @@ module Hecks
         # A cross-domain trigger (`across "Compliance"`) is spoken as words with the
         # domain named, since there is nothing here to link to.
         def policy_sentence(policy, index)
-          sentence = "When #{index.link(:event, bare(policy.on_event))} happens, #{asked_phrase(policy, index)}"
+          sentence = "When #{trigger_phrase(bare(policy.on_event), index)}, #{asked_phrase(policy, index)}"
           if policy.for_each
             query_holder, query = split_trigger(policy.for_each)
             sentence += ", once for each row of #{index.link(:query, query, within: query_holder)}"
@@ -75,6 +77,14 @@ module Hecks
           "#{sentence}."
         end
 
+        # "Topping added happens", or, for an event nothing here records, its name in quotes
+        # and where it comes from.
+        def trigger_phrase(event, index)
+          return "#{index.link(:event, event)} happens" if index[:event, event]
+
+          "\"#{Naming.words(event)}\" arrives from outside"
+        end
+
         # What the policy asks of whom, linked unless the trigger crosses into another domain.
         def asked_phrase(policy, index)
           holder, command = split_trigger(policy.trigger_command)

data/lib/hecks/projections/glossary/slugs.rb

@@ -14,7 +14,10 @@ module Hecks
           take.call(Markdown.title(bluebook))
           sections.each do |section|
             section.slug = take.call(section.title)
-            section.terms.each { |entry| entry.slug = take.call(entry.headword) }
+            Groups.walk(section).each do |kind, item|
+              slug = take.call(kind == :group ? item : item.headword)
+              item.slug = slug unless kind == :group
+            end
           end
         end
 

data/lib/hecks/projections/glossary.rb

@@ -2,6 +2,7 @@ require_relative "../projector"
 require_relative "../naming"
 require_relative "statements"
 require_relative "glossary/sections"
+require_relative "glossary/groups"
 require_relative "glossary/sensitivity"
 require_relative "glossary/sentences"
 require_relative "glossary/mermaid"
@@ -77,7 +78,7 @@ module Hecks
       def with_headwords(entries, section_name)
         entries.each { |entry| entry.headword = Naming.words(entry.name) }
         entries.group_by(&:headword).each_value { |group| qualify_repeats(group, section_name) }
-        entries.sort_by { |entry| [entry.headword.downcase, entry.kind.to_s] }
+        entries.sort_by { |entry| [Groups.rank(entry), entry.headword.downcase, entry.kind.to_s] }
       end
 
       def qualify_repeats(group, section_name)

data/lib/hecks/projections/plain_english.rb

@@ -0,0 +1,97 @@
+require_relative "../naming"
+
+module Hecks
+  module Projections
+    # The few pieces of English grammar the statements and the glossary share: how a construct
+    # name is spoken as a noun, and how a command is spoken as something being done.
+    #
+    #   PlainEnglish.doing("AddTopping", "Order") # => "adding a topping"
+    #   PlainEnglish.doing("Purchase", "Order")   # => "purchasing an order"
+    module PlainEnglish
+      # Nouns that take no article: "accruing interest", never "accruing an interest".
+      UNCOUNTED = %w[interest money cash information data feedback equipment evidence].freeze
+
+      # Two-syllable verbs stressed on the last syllable, which double their final consonant.
+      DOUBLED = %w[submit commit admit permit omit refer prefer transfer occur control patrol compel
+                   expel regret equip rebut forget begin cancel].freeze
+
+      # One-word verbs that act on their holder through a preposition: "withdrawing from a
+      # card", never "withdrawing a card".
+      THROUGH = { "withdraw" => "from", "deposit" => "into" }.freeze
+
+      # Verbs written as one word whose "-ing" form splits back into a verb and a particle.
+      PHRASAL = {
+        "chargeback" => "charging back", "rollback" => "rolling back", "backup" => "backing up",
+        "setup" => "setting up", "signup" => "signing up", "checkout" => "checking out",
+        "login" => "logging in", "logout" => "logging out", "payout" => "paying out"
+      }.freeze
+
+      module_function
+
+      # A construct name as a lowercase noun phrase; acronyms keep their capitals.
+      #
+      # @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(" ")
+      end
+
+      # @param phrase [String] a spoken noun phrase
+      # @return [String] the phrase with its indefinite article, such as "an order"
+      def a(phrase) = "#{Naming.a_or_an(phrase)} #{phrase}"
+
+      # @param phrase [String] a spoken noun phrase
+      # @return [String] the phrase with its last word pluralised, such as "ATM cards"
+      def plural(phrase)
+        *head, last = phrase.split
+        [*head, Naming.plural(last)].join(" ")
+      end
+
+      # A state name as it is said: `charged_back` -> "charged back".
+      def state(name) = name.to_s.tr("_", " ")
+
+      # @param states [Array<String>] state names
+      # @return [String] the spoken states joined with "or"
+      def states(states) = Naming.to_sentence_list(states.map { |name| state(name) }, conj: "or")
+
+      # @param text [String] a sentence fragment
+      # @return [String] the fragment with its first letter capitalised
+      def upper(text) = text.sub(/\A[[: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.
+      #
+      # @param command_name [String] the command's name, such as `AddTopping`
+      # @param holder_name [String] the aggregate or entity the command is declared on
+      # @return [String] the lowercase phrase, such as "adding a topping"
+      def doing(command_name, holder_name)
+        verb, *rest = noun(command_name).split
+        holder = a(noun(holder_name))
+        return "marking #{holder} #{[verb, *rest].join(" ")}" if verb.end_with?("ed")
+        return [gerund(verb), THROUGH[verb], holder].compact.join(" ") if rest.empty?
+
+        "#{gerund(verb)} #{object(rest.join(" "))}"
+      end
+
+      # @param phrase [String] the words after a command's verb
+      # @return [String] the phrase with an article, unless it names something uncounted
+      def object(phrase) = UNCOUNTED.include?(phrase.split.last) ? phrase : a(phrase)
+
+      # The "-ing" form of a plain verb.
+      #
+      # @param verb [String] a lowercase verb, such as "purchase" or "log"
+      # @return [String] its "-ing" form, such as "purchasing" or "logging"
+      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}#{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/)
+    end
+  end
+end

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

@@ -163,8 +163,8 @@ module Hecks
         def local_name(argument) = "#{argument}_text"
 
         # @param argument [String] an argument's name
-        # @return [String] the Rust field, raw-escaped when the name is a keyword
-        def rust_field(argument) = RustVocabulary::RUST_KEYWORDS.include?(argument) ? "r##{argument}" : argument
+        # @return [String] the Rust field, escaped when the name is a keyword
+        def rust_field(argument) = RustVocabulary.field_name(argument)
       end
     end
   end

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

@@ -10,7 +10,7 @@ module Hecks
           "    /// order given. A template is read, never evaluated. Private: call",
           "    /// sites go through a site's typed `<Variant>Args::render_args`,",
           "    /// which formats and supplies every declared argument.",
-          "    fn render(&self, values: &[(&str, &str)]) -> String {",
+          "    fn render(self, values: &[(&str, &str)]) -> String {",
           "        let mut text = self.template().to_string();",
           "        for (key, value) in values {",
           "            text = text.replace(&format!(\"{{{key}}}\"), value);",
@@ -28,40 +28,38 @@ module Hecks
         def impl_lines(spec, variants, rows)
           enum = spec[:enum]
           ["impl #{enum} {",
-           constants(enum, variants, spec[:kind]),
-           rows.first.keys.map { |field| accessor(enum, field, variants, rows) },
-           from_name(enum, spec[:kind]),
-           extras(enum, variants, spec[:kind]),
+           constants(variants, spec[:kind]),
+           rows.first.keys.map { |field| accessor(field, variants, rows) },
+           from_name(spec[:kind]),
+           extras(variants, spec[:kind]),
            "}",
            ""]
         end
 
-        # @param enum [String] the enum's name
         # @param variants [Array<String>] the variant names
         # @param kind [Symbol] `:order`, `:templates` or `:set`
         # @return [Array<String>] the `ORDER` or `ALL` constant, as Rust lines
-        def constants(enum, variants, kind)
-          list = variants.map { |variant| "        #{enum}::#{variant}," }
+        def constants(variants, kind)
+          list = variants.map { |variant| "        Self::#{variant}," }
           if kind == :order
             ["    /// The declared step order, first to last.",
-             "    pub const ORDER: [#{enum}; #{variants.size}] = [", list, "    ];", ""]
+             "    pub const ORDER: [Self; #{variants.size}] = [", list, "    ];", ""]
           else
             ["    /// Every row, in declared order.",
-             "    pub const ALL: &'static [#{enum}] = &[", list, "    ];", ""]
+             "    pub const ALL: &'static [Self] = &[", list, "    ];", ""]
           end
         end
 
-        # @param enum [String] the enum's name
         # @param field [String] the row field the accessor reads
         # @param variants [Array<String>] the variant names
         # @param rows [Array<Hash>] the table's rows
         # @return [Array] the accessor, as Rust lines
-        def accessor(enum, field, variants, rows)
+        def accessor(field, variants, rows)
           arms = variants.zip(rows).map do |variant, row|
-            "            #{enum}::#{variant} => #{RustVocabulary.rust_string(row.fetch(field))},"
+            "            Self::#{variant} => #{RustVocabulary.rust_string(row.fetch(field))},"
           end
           ["    /// The row's declared `#{field}`.",
-           "    pub fn #{RustVocabulary.accessor_name(field)}(&self) -> &'static str {",
+           "    pub const fn #{RustVocabulary.accessor_name(field)}(&self) -> &'static str {",
            "        match self {",
            arms,
            "        }",
@@ -71,38 +69,35 @@ module Hecks
 
         # Built on the enum's own list and name accessor, not a string match, so no wildcard arm.
         #
-        # @param enum [String] the enum's name
         # @param kind [Symbol] `:order`, `:templates` or `:set`
         # @return [Array<String>] `from_name`, as Rust lines
-        def from_name(enum, kind)
+        def from_name(kind)
           list  = kind == :order ? "ORDER" : "ALL"
           field = kind == :templates ? "site" : RustVocabulary.name_field(kind)
           ["    /// The row whose `#{field}` is `name`, if any.",
-           "    pub fn from_name(name: &str) -> Option<#{enum}> {",
-           "        #{enum}::#{list}.iter().copied().find(|row| row.#{RustVocabulary.accessor_name(field)}() == name)",
+           "    pub fn from_name(name: &str) -> Option<Self> {",
+           "        Self::#{list}.iter().copied().find(|row| row.#{RustVocabulary.accessor_name(field)}() == name)",
            "    }",
            ""]
         end
 
-        # @param enum [String] the enum's name
         # @param variants [Array<String>] the variant names
         # @param kind [Symbol] `:order`, `:templates` or `:set`
         # @return [Array<String>] the methods only this kind of table has, as Rust lines
-        def extras(enum, variants, kind)
+        def extras(variants, kind)
           case kind
-          when :order then position_fn(enum, variants)
+          when :order then position_fn(variants)
           when :templates then RENDER_FN
           else []
           end
         end
 
-        # @param enum [String] the enum's name
         # @param variants [Array<String>] the variant names
         # @return [Array] `position`, as Rust lines
-        def position_fn(enum, variants)
-          arms = variants.each_with_index.map { |variant, index| "            #{enum}::#{variant} => #{index}," }
+        def position_fn(variants)
+          arms = variants.each_with_index.map { |variant, index| "            Self::#{variant} => #{index}," }
           ["    /// This step's index in `ORDER`.",
-           "    pub fn position(&self) -> usize {",
+           "    pub const fn position(&self) -> usize {",
            "        match self {",
            arms,
            "        }",

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

@@ -59,11 +59,11 @@ module Hecks
 
         # @return [Array<String>] the test that every row is found by its own name
         def name_test(enum, kind)
-          list = kind == :order ? "ORDER" : "ALL"
+          list = kind == :order ? "&#{enum}::ORDER" : "#{enum}::ALL"
           name = RustVocabulary.accessor_name(RustVocabulary.name_field(kind))
           ["    #[test]",
            "    fn every_row_is_found_by_its_own_name() {",
-           "        for row in #{enum}::#{list}.iter() {",
+           "        for row in #{list} {",
            "            assert_eq!(#{enum}::from_name(row.#{name}()), Some(*row));",
            "        }",
            "    }",

data/lib/hecks/projections/rust_vocabulary.rb

@@ -1,5 +1,7 @@
+require_relative "../naming"
 require_relative "../projector"
 require_relative "../runtime/refusal_wording"
+require_relative "../vocabulary"
 require_relative "vocabulary"
 require_relative "rust_vocabulary/enum_body"
 require_relative "rust_vocabulary/arguments"
@@ -33,12 +35,20 @@ module Hecks
                                       kind: :order }
       }.freeze
 
-      RUST_KEYWORDS = %w[as async await break const continue crate dyn else enum extern false fn for if impl in let loop
-                         match mod move mut pub ref return self static struct super trait true type unsafe use where
-                         while abstract become box do final macro override priv typeof unsized virtual yield try].freeze
+      # Keywords Rust refuses as a raw identifier, so they cannot take the `r#` escape.
+      NOT_RAW = %w[crate self Self super].freeze
 
       module_function
 
+      # @param name [String] a field's name
+      # @return [String] the Rust field: raw-escaped when a keyword, with a trailing underscore
+      #   when the keyword cannot be raw
+      def field_name(name)
+        return "#{name}_" if NOT_RAW.include?(name)
+
+        Hecks::Vocabulary.fetch("RustReservedWord").include?(name) ? "r##{name}" : name
+      end
+
       def call(bluebook:, options: {}) = render(bluebook)
 
       def render(bluebook)
@@ -121,14 +131,12 @@ module Hecks
       def accessor_name(field) = field == "refusal" ? "refusal_class" : field
 
       def variant_name(row, fields)
-        name = fields.map { |field| pascal(row.fetch(field)) }.join
+        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/)
 
         name
       end
 
-      def pascal(text) = text.to_s.split("_").map { |part| part[0].to_s.upcase + part[1..].to_s }.join
-
       # 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" }

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

@@ -97,12 +97,6 @@ module Hecks
           # @return [Boolean] whether `value` reaches `ratio` on every background
           def reads?(value, against, ratio) = against.all? { |back| contrast(value, back) >= ratio }
 
-          # @param background [String] a fill
-          # @param light [String] a light foreground to try
-          # @param dark [String] a dark foreground to try
-          # @return [String] whichever reads better on `background`
-          def foreground(background, light, dark) = contrast(light, background) >= contrast(dark, background) ? light : dark
-
           # @return [Float] the hue, in degrees, of a colour given by its channels
           def angle(red, green, blue, high, spread)
             degrees = if high == red then ((green - blue) / spread) % 6

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

@@ -0,0 +1,99 @@
+require_relative "../plain_english"
+
+module Hecks
+  module Projections
+    module Statements
+      # The statements a holder's lifecycle and commands carry: where it starts, what moves it
+      # between states, who does each command, and every rule a command checks before and after.
+      # Rule text is the author's own; only the command's name is turned into words around it.
+      #
+      #   Actions.rules(order) # => ["Adding a topping requires: at most 10 toppings.", ...]
+      module Actions
+        module_function
+
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct with a lifecycle
+        # @return [Array<String>] where it starts, then one sentence per move
+        def lifecycle(holder)
+          lifecycle = holder.respond_to?(:lifecycle) && holder.lifecycle
+          return [] unless lifecycle
+
+          start = "#{PlainEnglish.upper(PlainEnglish.a(PlainEnglish.noun(holder.hecks_name)))} " \
+                  "starts out #{PlainEnglish.state(lifecycle.default)}."
+          [start, *moves(lifecycle).map { |command, move| move_sentence(holder, command, move) }]
+        end
+
+        # Each command's moves, as `[command, { from: [...], to: state }]`, merged across the
+        # transitions a command declares from more than one state.
+        def moves(lifecycle)
+          merged = lifecycle.transitions.each_with_object({}) do |(command, transition), found|
+            key = [command.to_s, transition.target]
+            found[key] ||= { from: [], to: transition.target }
+            found[key][:from] |= Array(transition.from)
+          end
+          merged.map { |(command, _target), move| [command, move] }
+        end
+
+        # "Purchasing an order moves it from available to sold."
+        def move_sentence(holder, command, move)
+          doing = PlainEnglish.doing(command, holder.hecks_name)
+          noun = PlainEnglish.noun(holder.hecks_name)
+          object = doing.match?(/\b#{Regexp.escape(noun)}\b/) ? "it" : "the #{noun}"
+          "#{PlainEnglish.upper(doing)} #{move_phrase(move, object)}."
+        end
+
+        # "moves it from available to sold", "keeps it failed", or "moves it to closed".
+        #
+        # @param move [Hash] `{ from: [...], to: state }`, as `moves` answers it
+        # @param object [String] what is moved, such as "it" or "the order"
+        # @return [String] the verb phrase
+        def move_phrase(move, object)
+          to = PlainEnglish.state(move[:to])
+          return "keeps #{object} #{to}" if move[:from] == [move[:to]]
+          return "moves #{object} to #{to}" if move[:from].empty?
+
+          "moves #{object} from #{PlainEnglish.states(move[:from])} to #{to}"
+        end
+
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct the commands are on
+        # @return [Array<String>] each command's role, its rules, and what it guarantees after
+        def rules(holder)
+          holder.commands.flat_map { |command| command_rules(holder, command) }
+        end
+
+        def command_rules(holder, command)
+          doing = PlainEnglish.doing(command.hecks_name, holder.hecks_name)
+          role = command.role && "#{PlainEnglish.upper(doing)} is done by the #{PlainEnglish.noun(command.role)}."
+          [role, *checks(holder, command).map { |rule| "#{PlainEnglish.upper(doing)} requires: #{rule}." },
+           *command.ensures.map { |rule| "After #{doing}: #{text(rule)}." }].compact
+        end
+
+        # What a command checks first: the state it starts from, then each `given` in the
+        # author's words. The state is left out when a move sentence already says it.
+        #
+        # @param said_by_move [Boolean] whether a move sentence states the starting state
+        # @return [Array<String>] the rules, without a closing period
+        def checks(holder, command, said_by_move: true)
+          [state_check(holder, command, said_by_move), *command.givens.map { |rule| text(rule) }].compact
+        end
+
+        # "the order is available", for a command declared `from:` a state.
+        def state_check(holder, command, said_by_move)
+          return nil unless command.from
+          return nil if said_by_move && moved_by?(holder, command)
+
+          "the #{PlainEnglish.noun(holder.hecks_name)} is #{PlainEnglish.states(Array(command.from))}"
+        end
+
+        def moved_by?(holder, command)
+          lifecycle = holder.respond_to?(:lifecycle) && holder.lifecycle
+          return false unless lifecycle
+
+          lifecycle.transitions.any? { |name, _transition| name.to_s == command.hecks_name }
+        end
+
+        # A rule's description as written, without a trailing period.
+        def text(rule) = rule.description.to_s.strip.delete_suffix(".")
+      end
+    end
+  end
+end