hecks 3.13.0 → 4.0.0

data/lib/hecks/forms/app/commands.rb

@@ -28,11 +28,10 @@ module Hecks
         # @param page [Hash] optionally `status:`, the submitted `values:`, the `error:` to show and
         #   the `prefill:` values
         def command_form(domain, aggregate, command, action, **page)
-          html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}",
+          html(Humanize.phrase(command.hecks_name),
                CommandFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, command: command,
                                           action: action, **page.slice(:values, :error, :prefill)),
-               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
-                             [command.hecks_name, nil]],
+               breadcrumbs: verb_breadcrumbs(domain, aggregate, command),
                status:      page.fetch(:status, 200))
         end
 

data/lib/hecks/forms/app/queries.rb

@@ -25,11 +25,10 @@ module Hecks
         def query_html(domain, aggregate, query, asked)
           action = "/#{domain}/#{aggregate.hecks_name}/#{query.hecks_name}.html"
           results, error = asked.empty? ? [nil, nil] : run_query(domain, aggregate, query, asked)
-          html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}",
+          html(Humanize.phrase(query.hecks_name),
                QueryFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, query: query,
                                         action: action, params: asked, results: results, error: error),
-               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
-                             [query.hecks_name, nil]],
+               breadcrumbs: verb_breadcrumbs(domain, aggregate, query),
                status:      error ? 422 : 200)
         end
 

data/lib/hecks/forms/app/records.rb

@@ -12,9 +12,9 @@ module Hecks
           return respond(405, "text/plain", "GET only") unless request.get?
           return aggregate_json(chapter, aggregate) unless format == "html"
 
-          html("#{chapter.name}::#{aggregate.hecks_name}",
+          html(Naming.plural(Humanize.phrase(aggregate.hecks_name)),
                RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
-               breadcrumbs: [[chapter.name, "/"], [aggregate.hecks_name, nil]])
+               breadcrumbs: [[chapter.name, "/"], [Humanize.phrase(aggregate.hecks_name), nil]])
         end
 
         def aggregate_json(chapter, aggregate)
@@ -52,10 +52,22 @@ module Hecks
           # `id:` last, as in `aggregate_route`.
           return json(200, instance.state.merge(id: instance.id)) if format != "html"
 
-          html("#{domain}::#{aggregate.hecks_name} #{id}",
+          html("#{Humanize.phrase(aggregate.hecks_name)} #{id}",
                RecordRenderer.show(registry: @registry, domain: domain, aggregate: aggregate, id: id),
-               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
-                             [id, nil]])
+               breadcrumbs: aggregate_crumbs(domain, aggregate) + [[id, nil]])
+        end
+
+        # @return [Array<Array(String, String)>] the domain and aggregate crumbs every page
+        #   under an aggregate starts with, the aggregate named in words
+        def aggregate_crumbs(domain, aggregate)
+          [[domain, "/"], [Humanize.phrase(aggregate.hecks_name), "/#{domain}/#{aggregate.hecks_name}.html"]]
+        end
+
+        # @param verb [Bluebook::Command, Bluebook::Query] the command or query the page is for
+        # @return [Array<Array(String, String), Array(String, nil)>] the aggregate crumbs, then
+        #   the verb named in words as the current page
+        def verb_breadcrumbs(domain, aggregate, verb)
+          aggregate_crumbs(domain, aggregate) + [[Humanize.phrase(verb.hecks_name), nil]]
         end
 
         def find_aggregate(chapter, name)

data/lib/hecks/forms/command_form_renderer.rb

@@ -43,7 +43,7 @@ module Hecks
         fields_html = fields_markup(registry, domain, all_fields, form)
         action = form.fetch(:action)
         cancel = "/#{domain}/#{aggregate.hecks_name}"
-        [header(domain, aggregate, command), error_banner(form[:error]),
+        [header(aggregate, command), error_banner(form[:error]),
          form_markup(action, fields_html, command, cancel).chomp,
          inspect_panel(domain, aggregate, command, action, all_fields)].join("\n").concat("\n")
       end
@@ -64,7 +64,7 @@ module Hecks
           <form method="post" action="#{Escape.attr(action)}" novalidate>
             #{fields_html}
             <div class="actions">
-              <button type="submit">#{Escape.html(command.hecks_name)}</button>
+              <button type="submit">#{Escape.html(Humanize.phrase(command.hecks_name))}</button>
               <a class="button secondary" href="#{Escape.attr(cancel)}">Cancel</a>
             </div>
           </form>
@@ -72,33 +72,58 @@ module Hecks
       end
 
       # Builds the `to` field a non-creating command uses to name the record it acts on,
-      # labelled with the aggregate's identity paths.
+      # labelled with the aggregate's name and helped by what identifies one ("the order's
+      # name").
       #
       # @param aggregate [Bluebook::Aggregate] the aggregate whose records the picker offers
       # @return [Forms::Field] a `:reference` field at path `"to"` targeting `aggregate`
       def self.identity_field(aggregate)
-        Field.new(path: "to", label: "#{aggregate.hecks_name} (#{aggregate.identity_paths.join(", ")})",
+        noun = Humanize.noun(aggregate.hecks_name)
+        Field.new(path: "to", label: Humanize.phrase(aggregate.hecks_name),
                   kind: :reference, html_type: "text", target_aggregate: aggregate,
-                  help: "The record this command acts on.")
+                  help: "Which #{noun} this is for, by the #{noun}'s #{identity_words(aggregate)}.")
       end
 
-      # Renders the form's heading: the command's qualified name, its role and creates
-      # badges, its goal, and its preconditions callout.
+      # Names what identifies a record in words: `["name.value"]` -> "name", a composite
+      # `["bank", "number"]` -> "bank and number". A dotted path names its first segment,
+      # since the hops after it reach inside a value object.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose identity is named
+      # @return [String] the identity's field names as lowercase words; "id" when it has none
+      def self.identity_words(aggregate)
+        names = aggregate.identity_paths.map { |path| Humanize.noun(path.to_s.split(".").first) }.uniq
+        names.empty? ? "id" : Naming.to_sentence_list(names)
+      end
+
+      # Renders the form's heading: the command's name in words, its role and creates
+      # badges, its goal, and its preconditions callout. The code name stays in the inspect
+      # panel.
       #
-      # @param domain [String] name of the domain (chapter) the aggregate belongs to
       # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
       # @param command [Bluebook::Command] the command being described
       # @return [String] HTML for the heading block
-      def self.header(domain, aggregate, command)
+      def self.header(aggregate, command)
         <<~HTML
-          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}")}</h1>
-          #{%(<span class="badge role" title="Declared on the command; this prototype dispatches with no caller bound, so the check does not run.">role: #{Escape.html(command.role)} (not enforced here)</span>) if command.role}
-          #{%(<span class="badge">creates a new #{Escape.html(aggregate.hecks_name)}</span>) if command.creates?}
+          <h1>#{Escape.html(Humanize.phrase(command.hecks_name))}</h1>
+          #{role_badge(command)}
+          #{%(<span class="badge">Creates a new #{Escape.html(Humanize.noun(aggregate.hecks_name))}</span>) if command.creates?}
           #{%(<p class="goal">#{Escape.html(command.goal)}</p>) if command.goal}
           #{givens_callout(command)}
         HTML
       end
 
+      # Names who the command is for. The preview dispatches with no caller bound, so the role
+      # is shown but not checked, and the badge says so.
+      #
+      # @param command [Bluebook::Command] the command whose declared role is shown
+      # @return [String] HTML for the badge, or `""` when the command declares no role
+      def self.role_badge(command)
+        return "" unless command.role
+
+        title = "The bluebook declares who does this. This preview signs nobody in, so it does not check."
+        %(<span class="badge role" title="#{title}">Done by: #{Escape.html(command.role)} (not checked in this preview)</span>)
+      end
+
       # Renders the command's `given` preconditions as a callout, so a caller sees what
       # would refuse the submission before making it.
       #
@@ -108,7 +133,8 @@ module Hecks
         return "" if command.givens.empty?
 
         items = command.givens.map { |given| "<li>#{Escape.html(given.description)}</li>" }
-        %(<div class="callout"><strong>Preconditions</strong> — refused if any fail:<ul>#{items.join}</ul></div>)
+        %(<div class="callout"><strong>Checked first.</strong> The action is refused if any of these fail:) \
+          "<ul>#{items.join}</ul></div>"
       end
 
       # Renders a refused submission as an alert banner carrying the refusal's class name
@@ -121,7 +147,7 @@ module Hecks
 
         <<~HTML
           <div class="error-banner" role="alert">
-            <p><strong>#{Escape.html(error.class.name.split("::").last)}</strong> — #{Escape.html(error.message)}</p>
+            <p><strong>Refused (#{Escape.html(error.class.name.split("::").last)}):</strong> #{Escape.html(error.message)}</p>
           </div>
         HTML
       end
@@ -174,9 +200,9 @@ module Hecks
       def self.inspect_head(verb, command, curl)
         <<~HTML
           <details class="inspect">
-            <summary>Inspect — #{Escape.html(verb)}</summary>
+            <summary>Inspect: #{Escape.html(verb)}</summary>
             <p>Emits: #{emitted_events(command)}</p>
-            <p>Equivalent request (as <code>curl</code>) — every field is <code>#{Escape.html("name.path")}</code>-encoded, form or JSON alike:</p>
+            <p>The same request as <code>curl</code>. Every field is sent by its dotted path (<code>#{Escape.html("name.path")}</code>), as a form or as JSON:</p>
             <div class="link-row"><code id="curl-snippet">#{Escape.html(curl)}</code><button type="button" class="copy" data-copy="#curl-snippet">copy</button></div>
         HTML
       end

data/lib/hecks/forms/field_controls.rb

@@ -65,7 +65,7 @@ module Hecks
             %(<option value="#{Escape.attr(option_value)}"#{" selected" if option_value.to_s == selected.to_s}>) \
               "#{Escape.html(option_label)}</option>"
           end
-          blank = field.optional? ? %(<option value="">—</option>) : ""
+          blank = field.optional? ? %(<option value="">(none)</option>) : ""
           select_tag(field, "#{blank}#{options.join}")
         end
 
@@ -80,7 +80,7 @@ module Hecks
         end
 
         def self.reference_blank(field, value)
-          return %(<option value="">—</option>) if field.optional?
+          return %(<option value="">(none)</option>) if field.optional?
 
           %(<option value="" disabled#{" selected" unless value}>choose one…</option>)
         end

data/lib/hecks/forms/field_renderer.rb

@@ -51,7 +51,7 @@ module Hecks
 
       def self.list_tail(field, item)
         <<~HTML
-            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{" — each line is one JSON object" unless item.leaf?}.</span>
+            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{", each line one JSON object" unless item.leaf?}.</span>
           </div>
         HTML
       end

data/lib/hecks/forms/field_shape.rb

@@ -3,6 +3,7 @@ require_relative "../bluebook/attribute"
 require_relative "../naming"
 require_relative "value_object_shape"
 require_relative "text_shape"
+require_relative "rule_words"
 
 module Hecks
   # The forms surface: the `expose` DSL, the IR->HTML renderers and the Rack app (see forms.rb).
@@ -32,9 +33,20 @@ module Hecks
         Naming.words(segment)
       end
 
-      # "amount.cents" -> "Amount → Cents", for a fieldset legend spanning several hops.
-      def self.breadcrumb(path)
-        path.to_s.split(".").map { |part| label(part) }.join(" → ")
+      # A code name as a phrase: "AddTopping" -> "Add topping", "Order" -> "Order".
+      #
+      # @param name [String, Symbol, #to_s] a command, query or aggregate name
+      # @return [String] the sentence-cased words
+      def self.phrase(name) = Naming.words(name)
+
+      # A code name as words inside a sentence: "BankAccount" -> "bank account", "ATMCard" ->
+      # "ATM card".
+      #
+      # @param name [String, Symbol, #to_s] an aggregate or field name
+      # @return [String] the words, the first lowercased unless it is an acronym
+      def self.noun(name)
+        words = Naming.words(name)
+        words.match?(/\A[A-Z]{2,}\b/) ? words : words.sub(/\A./, &:downcase)
       end
     end
 
@@ -79,12 +91,8 @@ module Hecks
 
       def self.reference_field(attribute, common)
         target = attribute.type.resolve
-        Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target,
-                            help: if target
-                                    "References an existing #{target.hecks_name} by id."
-                                  else
-                                    "References an aggregate in another domain — enter its id."
-                                  end)
+        help = target ? "An existing #{Humanize.noun(target.hecks_name)}, by its id." : "A record in another domain, by its id."
+        Field.new(**common, kind: :reference, html_type: "text", target_aggregate: target, help: help)
       end
 
       # Mirrors Runtime::Value::Admission#admitted_members (same split, chapter walk and
@@ -119,16 +127,26 @@ module Hecks
         return closed_set_field(shape, common) if shape.closed_set?
         return money_field(shape, common) if ValueObjectShape.money?(shape)
 
-        # A single-attribute value object names a scalar, not a group: unwrap it so the form
-        # asks for one thing and the inner attribute's own pattern drives the input type.
-        if (inner = ValueObjectShape.sole_attribute(shape))
-          return resolve(inner, aggregate: aggregate, path: "#{common[:path]}.#{inner.name}")
-                 .tap { |field| field.optional = common[:optional] || field.optional }
-        end
+        inner = ValueObjectShape.sole_attribute(shape)
+        return sole_attribute_field(shape, inner, aggregate, common) if inner
 
         group_field(shape, aggregate, common)
       end
 
+      # A single-attribute value object names a scalar, not a group: unwrap it so the form
+      # asks for one thing and the inner attribute's own pattern drives the input type. The
+      # label stays the command's own name for it (`topping`), never the inner `value`, and
+      # the help says what the value object's rules accept.
+      #
+      # @return [Forms::Field] the inner attribute's field at the dotted path
+      def self.sole_attribute_field(shape, inner, aggregate, common)
+        field = resolve(inner, aggregate: aggregate, path: "#{common[:path]}.#{inner.name}")
+        field.label = common[:label]
+        field.optional = common[:optional] || field.optional
+        field.help = RuleWords.describe(inner, shape.invariants) if field.leaf? && field.kind != :reference
+        field
+      end
+
       def self.cross_aggregate_value_object(aggregate, type_name)
         aggregate.hecks_owner&.aggregates&.each do |sibling|
           found = sibling.value_object(type_name)
@@ -145,10 +163,10 @@ module Hecks
       def self.money_field(shape, common)
         cents = Field.new(path: "#{common[:path]}.cents", label: "Amount (cents)", kind: :number,
                           html_type: "number", step: "1", optional: common[:optional],
-                          default: shape.attribute(:cents)&.default, help: "Whole cents — 1050 is $10.50.")
+                          default: shape.attribute(:cents)&.default, help: "In cents: 1050 is $10.50.")
         currency = Field.new(path: "#{common[:path]}.currency", label: "Currency", kind: :text, html_type: "text",
                              optional: true, default: shape.attribute(:currency)&.default || "USD",
-                             help: "Three-letter code.")
+                             help: "Three-letter code, such as USD.")
         Field.new(path: common[:path], label: common[:label], kind: :money, optional: common[:optional],
                   children: [cents, currency])
       end
@@ -173,6 +191,7 @@ module Hecks
       end
 
       def self.primitive_field(attribute, common)
+        common = common.merge(help: RuleWords.describe(attribute))
         case attribute.type.to_s
         when "Integer" then Field.new(**common, kind: :number, html_type: "number", step: "1")
         when "Float"   then Field.new(**common, kind: :number, html_type: "number", step: "any")

data/lib/hecks/forms/index_renderer.rb

@@ -1,4 +1,5 @@
 require_relative "html"
+require_relative "field_shape"
 
 module Hecks
   module Forms
@@ -40,7 +41,7 @@ module Hecks
                  "#{aggregate.queries.size} quer#{aggregate.queries.size == 1 ? "y" : "ies"}"
         <<~HTML
           <li><a href="/#{Escape.attr(name)}/#{Escape.attr(aggregate.hecks_name)}.html">
-            <span>#{Escape.html(aggregate.hecks_name)}</span><span class="kind">#{Escape.html(counts)}</span>
+            <span>#{Escape.html(Humanize.phrase(aggregate.hecks_name))}</span><span class="kind">#{Escape.html(counts)}</span>
           </a></li>
         HTML
       end

data/lib/hecks/forms/page.rb

@@ -35,7 +35,7 @@ module Hecks
           #{body}
           </main>
           <footer class="site-footer">
-            <p>Generated straight from the loaded bluebook IR — nothing here is hand-authored per page. See <code>docs/command-form-and-query-form-bluebook.md</code>.</p>
+            <p>Every page here is generated from the domain's description (its bluebook). None is written by hand.</p>
           </footer>
           <script>#{SCRIPT}</script>
           </body>

data/lib/hecks/forms/params.rb

@@ -203,19 +203,6 @@ module Hecks
         end
         into
       end
-
-      # Renders held values as a URL query string, percent-encoding each flattened path and
-      # value.
-      #
-      # @param fields [Array<Forms::Field>] the field tree naming which paths to read
-      # @param values [Hash{String, Symbol => Object}] held values, flat or nested; see
-      #   `FieldRenderer.dig`
-      # @return [String] `key=value` pairs joined with `&`, without a leading `?`; `""` when
-      #   `flatten` yields no pairs
-      def self.to_query_string(fields, values)
-        pairs = flatten(fields, values)
-        pairs.map { |key, value| "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(value)}" }.join("&")
-      end
     end
   end
 end

data/lib/hecks/forms/query_form_renderer.rb

@@ -22,7 +22,7 @@ module Hecks
         reference_options = ReferenceOptions.collect(registry, domain, fields)
 
         <<~HTML
-          #{header(domain, aggregate, query)}
+          #{header(query)}
           #{canonical_link(action, fields)}
           #{quick_links(action, fields)}
           #{filter_form(action, fields, view.fetch(:params, {}), reference_options)}
@@ -32,9 +32,9 @@ module Hecks
         HTML
       end
 
-      def self.header(domain, aggregate, query)
+      def self.header(query)
         <<~HTML
-          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}")}</h1>
+          <h1>#{Escape.html(Humanize.phrase(query.hecks_name))}</h1>
           #{%(<p class="goal">#{Escape.html(query.description)}</p>) if query.description}
           #{badges(query)}
         HTML
@@ -50,7 +50,7 @@ module Hecks
         paths = Params.paths(fields)
         template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join("&")}"
         <<~HTML
-          <p class="help">Every query is a plain GET — this exact URL is bookmarkable, linkable from a dashboard, curlable, whatever a feature needs:</p>
+          <p class="help">This query is a plain link. Bookmark it, share it, or put it on a dashboard:</p>
           <div class="link-row"><code id="canonical-link">#{Escape.html(template)}</code><button type="button" class="copy" data-copy="#canonical-link">copy</button></div>
         HTML
       end
@@ -81,7 +81,8 @@ module Hecks
       def self.error_banner(error)
         return "" unless error
 
-        %(<div class="error-banner" role="alert"><p><strong>#{Escape.html(error.class.name.split("::").last)}</strong> — ) \
+        kind = Escape.html(error.class.name.split("::").last)
+        %(<div class="error-banner" role="alert"><p><strong>Refused (#{kind}):</strong> ) \
           "#{Escape.html(error.message)}</p></div>"
       end
 
@@ -96,7 +97,7 @@ module Hecks
         paths = Params.paths(fields)
         <<~HTML
           <details class="inspect">
-            <summary>Inspect — #{Escape.html(verb)}</summary>
+            <summary>Inspect: #{Escape.html(verb)}</summary>
             <p>Parameters: #{paths.empty? ? "<em>none</em>" : paths.map { |p| "<code>#{Escape.html(p)}</code>" }.join(", ")}</p>
             <pre>#{Escape.html(JSON.pretty_generate(query.to_h))}</pre>
           </details>

data/lib/hecks/forms/record_renderer.rb

@@ -11,7 +11,7 @@ module Hecks
       def self.index(registry:, domain:, aggregate:)
         instances = registry.repository(domain, aggregate).all
         <<~HTML
-          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}")}</h1>
+          <h1>#{Escape.html(Naming.plural(Humanize.phrase(aggregate.hecks_name)))}</h1>
           #{%(<p class="goal">#{Escape.html(aggregate.description)}</p>) if aggregate.description}
           #{creating_links(domain, aggregate)}
           <h2>Records (#{instances.size})</h2>
@@ -26,7 +26,7 @@ module Hecks
 
         links = creators.map do |cmd|
           %(<a class="button" href="/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html">) \
-            "+ #{Escape.html(cmd.hecks_name)}</a>"
+            "+ #{Escape.html(Humanize.phrase(cmd.hecks_name))}</a>"
         end
         %(<div class="actions">#{links.join}</div>)
       end
@@ -40,7 +40,7 @@ module Hecks
         state = instance.state
         current = aggregate.lifecycle && state[aggregate.lifecycle.field]
         <<~HTML
-          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}")} <span class="mono">#{Escape.html(id)}</span></h1>
+          <h1>#{Escape.html(Humanize.phrase(aggregate.hecks_name))} <span class="mono">#{Escape.html(id)}</span></h1>
           #{lifecycle_badge(aggregate, current)}
           #{state_table(state)}
           <h2>Commands</h2>
@@ -76,7 +76,8 @@ module Hecks
       # Omits lifecycle transitions that dispatch would refuse from the current state.
       def self.command_links(domain, aggregate, id, current_state)
         commands = aggregate.commands.reject(&:creates?).select { |cmd| applies?(aggregate, cmd, current_state) }
-        return "<p><em>No commands act on an existing #{Escape.html(aggregate.hecks_name)}.</em></p>" if commands.empty?
+        noun = Escape.html(Humanize.noun(aggregate.hecks_name))
+        return "<p><em>No commands act on an existing #{noun}.</em></p>" if commands.empty?
 
         items = commands.map { |cmd| command_item(domain, aggregate, cmd, id) }
         %(<ul class="verb-list">#{items.join}</ul>)
@@ -86,7 +87,7 @@ module Hecks
       def self.command_item(domain, aggregate, cmd, id)
         # The id is free-form, so it is percent-encoded as a query value.
         href = "/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html?to=#{Escape.url(id)}"
-        %(<li><a href="#{Escape.attr(href)}"><span>#{Escape.html(cmd.hecks_name)}</span>) \
+        %(<li><a href="#{Escape.attr(href)}"><span>#{Escape.html(Humanize.phrase(cmd.hecks_name))}</span>) \
           "<span class=\"kind\">#{Escape.html(cmd.goal.to_s)}</span></a></li>"
       end
 
@@ -110,15 +111,18 @@ module Hecks
 
         cmd_items = commands.map { |c| verb_item(domain, aggregate, c, "command") }
         query_items = aggregate.queries.map { |q| verb_item(domain, aggregate, q, "query") }
-        %(<h2>Every command &amp; query on #{Escape.html(aggregate.hecks_name)}</h2>) \
+        %(<h2>Commands and queries for #{plural_noun(aggregate)}</h2>) \
           "<ul class=\"verb-list\">#{(cmd_items + query_items).join}</ul>"
       end
 
       # @param kind [String] the word shown beside the verb, `"command"` or `"query"`
       # @return [String] the list item linking to the verb's own page
+      # @return [String] the aggregate's name as a lowercase plural, HTML-escaped: "orders"
+      def self.plural_noun(aggregate) = Escape.html(Naming.plural(Humanize.noun(aggregate.hecks_name)))
+
       def self.verb_item(domain, aggregate, verb, kind)
         %(<li><a href="/#{domain}/#{aggregate.hecks_name}/#{verb.hecks_name}.html">) \
-          "<span>#{Escape.html(verb.hecks_name)}</span><span class=\"kind\">#{kind}</span></a></li>"
+          "<span>#{Escape.html(Humanize.phrase(verb.hecks_name))}</span><span class=\"kind\">#{kind}</span></a></li>"
       end
     end
   end

data/lib/hecks/forms/rule_words.rb

@@ -0,0 +1,100 @@
+require_relative "../bluebook/named_pattern"
+
+module Hecks
+  module Forms
+    module FieldShape
+      # Says in plain words what a field accepts, read only from what the bluebook declares:
+      # the attribute's type, its named `matches:` pattern, and the invariants of the value
+      # object it sits in. An invariant this module cannot read is quoted by its own
+      # description rather than guessed at.
+      module RuleWords
+        # Words for each `Bluebook::NamedPattern` name; a raw regex has none and is not shown.
+        PATTERN_WORDS = {
+          present:       "Must not be blank.",
+          not_empty:     "Must not be empty.",
+          no_whitespace: "No spaces.",
+          snake_name:    "Lowercase letters, digits and underscores, starting with a letter.",
+          git_sha:       "A commit id: 7 to 40 hexadecimal characters.",
+          digits:        "Digits only."
+        }.freeze
+
+        # The noun a numeric type reads as, for "A whole number above zero."
+        NUMBER_NOUNS = { "Integer" => "A whole number", "Float" => "A number" }.freeze
+
+        # One comparison of the attribute against a literal number, as its canonical source
+        # spells it: `value > 0`, `cents >= 0`.
+        COMPARISON = /\A(?<name>\w+) (?<op>>=|<=|>|<) (?<bound>-?\d+(?:\.\d+)?)\z/
+
+        # How each comparison reads after the noun: "above 5", "10 or less".
+        BOUND_WORDS = { ">" => "above %s", ">=" => "%s or more", "<" => "below %s", "<=" => "%s or less" }.freeze
+
+        module_function
+
+        # Describes what `attribute` accepts, or nil when nothing declared can be said in words.
+        #
+        # @param attribute [Bluebook::Attribute] the scalar attribute the field asks for
+        # @param invariants [Array<Bluebook::Invariant>] the rules of the value object that
+        #   wraps `attribute`; empty for a bare attribute
+        # @return [String, nil] one or more sentences, such as "A whole number above zero."
+        def describe(attribute, invariants = [])
+          readable, quoted = invariants.partition { |rule| reading(attribute, rule) }
+          sentences = [type_sentence(attribute, readable), pattern_sentence(attribute, readable)]
+          sentences += quoted.map { |rule| "Rule: #{rule.description}." }
+          text = sentences.compact.uniq.join(" ")
+          text.empty? ? nil : text
+        end
+
+        # @return [String, nil] the numeric noun with every readable bound, such as
+        #   "A whole number above zero." or "A whole number, zero or more."; nil for a
+        #   non-numeric attribute
+        def type_sentence(attribute, readable)
+          noun = NUMBER_NOUNS[attribute.type.to_s]
+          return nil unless noun
+
+          bounds = Naming.to_sentence_list(readable.map { |rule| reading(attribute, rule) }.grep_v(:not_blank))
+          return "#{noun}." if bounds.empty?
+
+          "#{noun}#{bounds.start_with?("above", "below") ? " " : ", "}#{bounds}."
+        end
+
+        # @return [String, nil] "Must not be blank." when the named pattern or a readable
+        #   invariant says so, or the named pattern's own words
+        def pattern_sentence(attribute, readable)
+          named = Bluebook::NamedPattern::TABLE.key(attribute.pattern.to_s)
+          return PATTERN_WORDS.fetch(:present) if readable.any? { |rule| reading(attribute, rule) == :not_blank }
+
+          named && PATTERN_WORDS[named]
+        end
+
+        # Reads one invariant over the attribute alone.
+        #
+        # @return [String, Symbol, nil] a bound's words ("above zero"), `:not_blank`, or nil
+        #   when the rule is not one this module can read
+        def reading(attribute, rule)
+          name = attribute.name.to_s
+          canonical = rule.canonical.to_s.strip
+          return :not_blank if blank_check?(name, canonical)
+          return "above zero" if canonical == "#{name}.positive?"
+
+          comparison_words(name, canonical)
+        end
+
+        # @return [Boolean] whether the rule refuses an empty or all-whitespace value
+        def blank_check?(name, canonical)
+          ["!#{name}.to_s.empty?", "!#{name}.to_s.strip.empty?", "!#{name}.empty?", "!#{name}.strip.empty?"]
+            .include?(canonical)
+        end
+
+        # @return [String, nil] the comparison's words, with zero spelled out; nil when the
+        #   rule is not one comparison of `name` against a number
+        def comparison_words(name, canonical)
+          match = COMPARISON.match(canonical)
+          return nil unless match && match[:name] == name
+
+          bound = match[:bound] == "0" ? "zero" : match[:bound]
+          format(BOUND_WORDS.fetch(match[:op]), bound)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/forms/value_object_shape.rb

@@ -1,7 +1,8 @@
 module Hecks
   module Forms
     # Shared value-object shape classification, so callers such as
-    # field_shape.rb, ui_schema.rb and sql_query_builder.rb agree on it.
+    # field_shape.rb and sql_query_builder.rb agree on it. There is no Ruby ui_schema; the Rust
+    # host builds the UI schema (rust/host/src/ui_schema.rs) from the same field-shape rules.
     module ValueObjectShape
       module_function
 

data/lib/hecks/framework/bluebook/change.bluebook

@@ -18,14 +18,14 @@ Hecks.bluebook "Change" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a change is named") { !value.to_s.empty? }
     end
 
     # The name the script is registered under with the adapter.
     value_object "ScriptName" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a change names its script") { !value.to_s.empty? }
     end

data/lib/hecks/fuzzing/bounded_exhaustive_expressions.rb

@@ -35,9 +35,6 @@ module Hecks
         array:   %w[arr_num arr_str].freeze
       }.freeze
 
-      # Element type per array attribute, so a block parameter gets the right leaf set.
-      ARRAY_ELEMENT_TYPE = { "arr_num" => :numeric, "arr_str" => :string }.freeze
-
       BLOCK_PARAM = "el".freeze
 
       MAX_DEPTH = 3

data/lib/hecks/fuzzing/domain_generator/block_rendering.rb

@@ -19,7 +19,7 @@ module Hecks
         end
 
         def string_body(name)
-          ["attribute :value, String, pattern: '[^ \\t\\n\\r]'",
+          ["attribute :value, String, matches: :present",
            "invariant(#{"a #{name} is not blank".inspect}) { !value.to_s.empty? }"]
         end