hecks 4.0.0 → 6.0.0

data/lib/hecks/site/bluebook/site.bluebook

@@ -1,23 +1,23 @@
-# The Site chapter: the route table a client declares for its website, and the command that
+# The Site bluebook: the route table a client declares for its website, and the command that
 # projects it into the TypeScript the site reads.
 #
-# A client declares its routes as `member` rows of a `value_object "Route"` in its own chapter (the
+# A client declares its routes as `member` rows of a `value_object "Route"` in its own bluebook (the
 # Route aggregate below names every field a row may carry and the closed sets its values come from),
-# attaches this chapter, and runs `hecks site site_projection.project_site`. The projection (`:site_routes_ts`)
+# attaches this bluebook, and runs `hecks site site_projection.project_site`. The projection (`:site_routes_ts`)
 # writes one `routes.ts` the site's middleware, navigation, sitemap, robots file and CMS all import,
 # so a route is declared once. The Route aggregate's value objects are the one place the closed
 # vocabularies live: the projector reads them from here, so a row naming a cache class that is
 # not a member is refused with the members listed.
 #
 # The same command projects the CDN: a project that adds Edge, EdgePolicy, EdgeOrigin and EdgeRule rows
-# to its chapter has the CloudFront behaviours and the listener rules written into the marked regions
+# to its bluebook has the CloudFront behaviours and the listener rules written into the marked regions
 # of the template it owns (the `:site_cdn` projection). Those rows are the template's facts, so only the
 # closed sets they draw on, cache class, origin and the kind of an EdgeFunction row, are named here. A
 # route's `edge:` names an EdgeFunction row, a viewer-request function the projection writes into the
 # template's `edge_functions` region and attaches to that route's behaviour.
 #
 # Each run records that it was requested before the SiteToolchain port is asked, and what came of
-# it after. No command declares a role: the chapter boots standing alone.
+# it after. No command declares a role: the bluebook boots standing alone.
 Hecks.bluebook "Site" do
   vision "Declare a site's routes once and project them into the TypeScript its pages, navigation and CMS read."
 
@@ -39,7 +39,7 @@ Hecks.bluebook "Site" do
 
     # `/blog/:slug.html` names a parameter; a trailing `/*` matches everything beneath a prefix. A
     # row with a `command:` or `query:` source may leave its path out, and the projection derives it
-    # from the forms scheme (`/Chapter/Aggregate/Verb`).
+    # from the forms scheme (`/Bluebook/Aggregate/Verb`).
     value_object "Path" do
       attribute :value, String, pattern: '\A(/[^ \t\n\r]*)?\z'
     end
@@ -100,8 +100,8 @@ Hecks.bluebook "Site" do
 
     # Where a page's content comes from, one of `none`, `global:<slug>` (a CMS global),
     # `collection:<name>` (a CMS collection, whose rows fill the path's parameter),
-    # `command:<Chapter>.<Aggregate>.<Command>` or `query:<Chapter>.<Aggregate>.<Query>`. The last
-    # two are checked against the chapters the project attaches.
+    # `command:<Bluebook>.<Aggregate>.<Command>` or `query:<Bluebook>.<Aggregate>.<Query>`. The last
+    # two are checked against the bluebooks the project attaches.
     value_object "Source" do
       attribute :value, String, pattern: '\A(none|(global|collection):[a-z0-9_-]+|(command|query):[A-Za-z0-9_]+\.[A-Za-z0-9_]+\.[A-Za-z0-9_]+)\z'
     end
@@ -134,7 +134,7 @@ Hecks.bluebook "Site" do
       invariant("a run is named") { !value.to_s.empty? }
     end
 
-    # A project directory, whose `bluebook/` holds the chapter that declares the route table.
+    # A project directory, whose `bluebook/` holds the bluebook that declares the route table.
     value_object "DomainPath" do
       attribute :value, String, matches: :not_empty
 
@@ -185,6 +185,7 @@ Hecks.bluebook "Site" do
       mark :failure, "faulted"
       transition "Complete" => "projected", from: "requested"
       transition "Fault"    => "faulted",   from: "requested"
+      mark :terminal, "faulted", "projected"
     end
 
     # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [cms=<dir>] [root=<dir>] [editor=<dir>] [extension=ts|mts] [--check]`.
@@ -193,25 +194,16 @@ Hecks.bluebook "Site" do
     command "ProjectSite" do
       goal "Project a site's route table into routes.ts, or with check only compare it with the file on disk"
 
-      attribute :domain,    DomainPath
-      attribute :run,       RunKey
-      attribute :out,       Location,  optional: true
-      attribute :template,  Location,  optional: true
-      attribute :cms,       Location,  optional: true
-      attribute :root,      Location,  optional: true
-      attribute :editor,    Location,  optional: true
-      attribute :extension, Extension, optional: true
-      attribute :check,     Switch,    optional: true
-
-      sets :domain
-      sets :run
-      sets :out
-      sets :template
-      sets :cms
-      sets :root
-      sets :editor
-      sets :extension
-      sets :check
+      attribute :domain,    DomainPath, sets: true
+      attribute :run,       RunKey, sets: true
+      attribute :out,       Location,  optional: true, sets: true
+      attribute :template,  Location,  optional: true, sets: true
+      attribute :cms,       Location,  optional: true, sets: true
+      attribute :root,      Location,  optional: true, sets: true
+      attribute :editor,    Location,  optional: true, sets: true
+      attribute :extension, Extension, optional: true, sets: true
+      attribute :check,     Switch,    optional: true, sets: true
+
 
       emits "SiteProjectionRequested"
     end
@@ -226,25 +218,18 @@ Hecks.bluebook "Site" do
     command "CheckLive" do
       goal "Compare a project's generated CloudFront behaviours with a live distribution's"
 
-      attribute :domain,       DomainPath
-      attribute :run,          RunKey
-      attribute :template,     Location,       optional: true
-      attribute :live,         Location,       optional: true
-      attribute :distribution, DistributionId, optional: true
-      attribute :expect_new,   PathList,       optional: true
-      attribute :refs,         PolicyRefs,     optional: true
+      attribute :domain,       DomainPath, sets: true
+      attribute :run,          RunKey, sets: true
+      attribute :template,     Location,       optional: true, sets: true
+      attribute :live,         Location,       optional: true, sets: true
+      attribute :distribution, DistributionId, optional: true, sets: true
+      attribute :expect_new,   PathList,       optional: true, sets: true
+      attribute :refs,         PolicyRefs,     optional: true, sets: true
 
       given("exactly one of a saved configuration and a distribution is named: pass live= or distribution=, not both") do
         (live.set? && distribution.unset?) || (live.unset? && distribution.set?)
       end
 
-      sets :domain
-      sets :run
-      sets :template
-      sets :live
-      sets :distribution
-      sets :expect_new
-      sets :refs
 
       emits "LiveCheckRequested"
     end
@@ -258,13 +243,10 @@ Hecks.bluebook "Site" do
     command "CheckSite" do
       goal "Ask a running site what its route table says it must answer, and judge each answer"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :url,    SiteUrl
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    RunKey, sets: true
+      attribute :url,    SiteUrl, sets: true
 
-      sets :domain
-      sets :run
-      sets :url
 
       emits "SiteProbeRequested"
     end
@@ -277,13 +259,10 @@ Hecks.bluebook "Site" do
     command "CheckRoles" do
       goal "Check a host on this machine refuses every role-declaring command from a caller with no role"
 
-      attribute :domain, DomainPath
-      attribute :run,    RunKey
-      attribute :url,    SiteUrl
+      attribute :domain, DomainPath, sets: true
+      attribute :run,    RunKey, sets: true
+      attribute :url,    SiteUrl, sets: true
 
-      sets :domain
-      sets :run
-      sets :url
 
       emits "RolesCheckRequested"
     end
@@ -292,9 +271,8 @@ Hecks.bluebook "Site" do
       goal "Record that routes.ts was written, or found current, or the live edge matched, and what it said"
 
       reference_to SiteProjection
-      attribute :output, Report
+      attribute :output, Report, sets: true
 
-      sets :output
 
       emits "SiteProjected"
     end
@@ -303,9 +281,8 @@ Hecks.bluebook "Site" do
       goal "Record that routes.ts could not be projected, or was out of date, and why"
 
       reference_to SiteProjection
-      attribute :refusal, Report
+      attribute :refusal, Report, sets: true
 
-      sets :refusal
 
       emits "SiteFaulted"
     end
@@ -326,22 +303,22 @@ Hecks.bluebook "Site" do
 
   policy "ProjectWhenRequested" do
     on      "SiteProjection.SiteProjectionRequested"
-    trigger SiteProjection::SiteToolchain::Project, with: { run: :run }
+    ask     :project, with: { run: :run }
   end
 
   policy "CheckWhenRequested" do
     on      "SiteProjection.LiveCheckRequested"
-    trigger SiteProjection::SiteToolchain::Compare, with: { run: :run }
+    ask     :compare, with: { run: :run }
   end
 
   policy "ProbeWhenRequested" do
     on      "SiteProjection.SiteProbeRequested"
-    trigger SiteProjection::SiteToolchain::Probe, with: { run: :run }
+    ask     :probe, with: { run: :run }
   end
 
   policy "RolesWhenRequested" do
     on      "SiteProjection.RolesCheckRequested"
-    trigger SiteProjection::SiteToolchain::Roles, with: { run: :run }
+    ask     :roles, with: { run: :run }
   end
 
   policy "RecordTheProjection" do

data/lib/hecks/site/bluebook/site.ports.hecksagon

@@ -1,4 +1,4 @@
-# The port Site declares, for every hecksagon that attaches the chapter (`Chapters` loads this file
+# The port Site declares, for every hecksagon that attaches the bluebook (`Bluebooks` loads this file
 # with it). Each projection asks the SiteToolchain port, which the Hecks domain binds
 # (lib/hecks/hecks/adapters/site_toolchain.rb): the outside a projection reaches. The ask is
 # answered with the record's own arguments or refused with a reason. The port has to be declared

data/lib/hecks/sme/bluebook/sme.bluebook

@@ -2,7 +2,7 @@
 #
 # An interview is the record of one conversation with a subject matter expert about a domain: what
 # was asked, what was said, and what a developer then accepted as established. It is development
-# time work, so this chapter ships in the gem but is not attached to the Hecks domain: nothing
+# time work, so this bluebook ships in the gem but is not attached to the Hecks domain: nothing
 # boots it except the command that runs an interview.
 Hecks.bluebook "SME" do
   vision "Learn a business from the people who know it: an interview with a subject matter expert, kept as a record of what was asked, what was said, and what was accepted as established."
@@ -119,6 +119,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptThing" => "accepted", from: "proposed"
         transition "RejectThing" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptThing", from: "proposed" do
@@ -156,6 +157,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptAction" => "accepted", from: "proposed"
         transition "RejectAction" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptAction", from: "proposed" do
@@ -188,6 +190,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptRule" => "accepted", from: "proposed"
         transition "RejectRule" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptRule", from: "proposed" do
@@ -223,6 +226,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptField" => "accepted", from: "proposed"
         transition "RejectField" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptField", from: "proposed" do
@@ -259,6 +263,7 @@ Hecks.bluebook "SME" do
       lifecycle :status, default: "proposed" do
         transition "AcceptTransition" => "accepted", from: "proposed"
         transition "RejectTransition" => "rejected", from: "proposed"
+        mark :terminal, "rejected"
       end
 
       command "AcceptTransition", from: "proposed" do
@@ -282,6 +287,7 @@ Hecks.bluebook "SME" do
       transition "Begin"    => "underway",  from: "planned"
       transition "Conclude" => "concluded", from: "underway"
       transition "Cancel"   => "cancelled", from: ["planned", "underway"]
+      mark :terminal, "cancelled", "concluded"
     end
 
     command "Plan" do

data/lib/hecks/storehouse/audit.rb

@@ -6,6 +6,9 @@ module Hecks
       # The caller-supplied fields of an audit line, in the order the line spells them.
       AUDIT_FIELDS = %i[verb summary source role actor_id].freeze
 
+      # A character a log file's name may not carry.
+      UNSAFE_NAME_CHARACTER = /[^A-Za-z0-9_-]/
+
       # Kept under Hecks::CacheDir, not the domain directory (part of the domain's
       # own state) or the gem directory (read-only once installed).
       # :nodoc:
@@ -13,7 +16,7 @@ module Hecks
 
       # :nodoc:
       def log_path(domain_name)
-        File.join(log_root, "#{domain_name.to_s.gsub(/[^A-Za-z0-9_-]/, "_")}.jsonl")
+        File.join(log_root, "#{domain_name.to_s.gsub(UNSAFE_NAME_CHARACTER, "_")}.jsonl")
       end
 
       # Never fails a real call because its own audit log couldn't be written —

data/lib/hecks/storehouse/bluebook_words.rb

@@ -0,0 +1,35 @@
+require_relative "../naming"
+
+module Hecks
+  module Storehouse
+    # Which bluebook a command or query name speaks to, read the way the CLI reads a line: the
+    # booted domain's own bluebook, or a bluebook its hecksagon attaches when the name starts with
+    # that bluebook's word and a space (`bulk bulk_run.request` reaches the attached Bulk bluebook).
+    # Extended onto `Storehouse`.
+    module BluebookWords
+      # The bluebook `name` speaks to, and the name within that bluebook.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param name [String, Symbol] a command or query name, optionally led by a bluebook word
+      # @return [Array(Bluebook::Declaration, String)] the bluebook, and the name with its bluebook
+      #   word
+      #   dropped
+      # @raise [Runtime::NotFound] if the boot loaded no bluebook
+      def bluebook_and_name(runtime, name)
+        word, rest = name.to_s.split(" ", 2)
+        attached = rest && attached_bluebook(runtime, word)
+        attached ? [runtime.bluebook(attached), rest] : [bluebook_for(runtime), name.to_s]
+      end
+
+      # The name of the bluebook the booted domain attaches under `word`, or nil.
+      #
+      # @param runtime [Runtime::Dispatcher] the booted domain
+      # @param word [String] a bluebook's snake-cased name, such as `"bulk"`
+      # @return [String, nil] the attached bluebook's name
+      def attached_bluebook(runtime, word)
+        own = bluebook_for(runtime)
+        Array(runtime.hecksagon(own.name)&.member_bluebooks).find { |declaration| Naming.snake(declaration) == word }
+      end
+    end
+  end
+end

data/lib/hecks/storehouse/dispatching.rb

@@ -17,7 +17,7 @@ module Hecks
       # @raise [ArgumentError] for any other keyword
       def dispatch(runtime:, command:, summary:, args: {}, **)
         request = Request.new(runtime: runtime, name: command, summary: summary, args: args, **)
-        request.bluebook = bluebook_for(runtime)
+        request.bluebook, request.name = bluebook_and_name(runtime, command)
         audited(request, request.dry_run ? "dry_run" : "dispatch") { perform_dispatch(request) }
       end
 
@@ -72,9 +72,12 @@ module Hecks
 
       # :nodoc:
       def settled_record(runtime, spec, result)
-        bluebook = bluebook_for(runtime)
+        bluebook = runtime.bluebook(spec[:command].to_s.split("::", 2).first) || bluebook_for(runtime)
         aggregate = top_level_aggregate(bluebook, spec[:command])
-        aggregate && runtime.registry.repository(bluebook.name, aggregate)&.find(result.id)&.to_h
+        return aggregate unless aggregate
+
+        repository = runtime.repository(bluebook.name, aggregate)
+        repository&.find(result.id)&.to_h
       end
 
       # :nodoc:

data/lib/hecks/storehouse/introspection.rb

@@ -40,12 +40,12 @@ module Hecks
           queries:  aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
       end
 
-      # One aggregate's (or the whole chapter's) full usage documentation — the
+      # One aggregate's (or the whole bluebook's) full usage documentation — the
       # same document hecks docs renders for a human.
       #
       # @param runtime [Runtime::Registry] the booted domain to describe
       # @param aggregate [String, Symbol, nil] one aggregate's name, or nil for the
-      #   whole chapter
+      #   whole bluebook
       # @return [Hash] :ok, :domain, :docs; or the refused shape
       # @raise [Runtime::NotFound] if aggregate names no known aggregate
       def describe(runtime:, aggregate: nil)
@@ -79,7 +79,7 @@ module Hecks
       # :nodoc:
       def model_findings(runtime)
         require_relative "../bluebook/model_check"
-        findings = runtime.registry.bluebooks.values.flat_map { |bluebook| Bluebook::ModelCheck.call(bluebook) }
+        findings = runtime.bluebooks.values.flat_map { |bluebook| Bluebook::ModelCheck.call(bluebook) }
         findings.map { |f| { kind: f.kind, severity: f.severity, subject: f.subject, message: f.message } }
       end
 
@@ -92,7 +92,7 @@ module Hecks
       def history(runtime:)
         bluebook = bluebook_for(runtime)
         entries  = bluebook.aggregates.each_with_object({}) do |aggregate, all|
-          repository = runtime.registry.repository(bluebook.name, aggregate)
+          repository = runtime.repository(bluebook.name, aggregate)
           all[aggregate.storage_name] = journal_entries(repository)
         end
 

data/lib/hecks/storehouse/querying.rb

@@ -17,7 +17,7 @@ module Hecks
       def query(runtime:, question:, summary:, args: {}, **options)
         check_options!(options, %i[source role actor_id])
         request = Request.new(runtime: runtime, name: question, summary: summary, args: args, **options)
-        request.bluebook = bluebook_for(runtime)
+        request.bluebook, request.name = bluebook_and_name(runtime, question)
         audited(request, "query") { perform_query(request) }
       end
 
@@ -62,7 +62,7 @@ module Hecks
       def perform_state(runtime, bluebook, aggregate, summary, id)
         require_summary!(summary)
         ir         = aggregate_ir!(bluebook, aggregate)
-        repository = runtime.registry.repository(bluebook.name, ir)
+        repository = runtime.repository(bluebook.name, ir)
         return ok(summary: summary, record: single_record(repository, ir, id)) if id
 
         records = repository.all.map { |instance| Adapters::Driving::Json.materialize(instance.to_h) }

data/lib/hecks/storehouse.rb

@@ -13,6 +13,7 @@ require_relative "storehouse/audit"
 require_relative "storehouse/dispatching"
 require_relative "storehouse/querying"
 require_relative "storehouse/introspection"
+require_relative "storehouse/bluebook_words"
 
 module Hecks
   # Dispatch/query/state and introspection over one booted domain, pure
@@ -40,6 +41,7 @@ module Hecks
     extend Dispatching
     extend Querying
     extend Introspection
+    extend BluebookWords
 
     module_function
 
@@ -59,7 +61,7 @@ module Hecks
     # the same one-bluebook-per-boot shape.
     # :nodoc:
     def bluebook_for(runtime)
-      runtime.registry.bluebooks.values.first or
+      runtime.first_bluebook or
         raise Runtime::NotFound, "this boot loaded no bluebook"
     end
 
@@ -67,7 +69,13 @@ module Hecks
     def aggregate_ir!(bluebook, name)
       bluebook.aggregate(name) or
         raise Runtime::NotFound, "#{bluebook.name} declares no aggregate named #{name.inspect} — " \
-                                 "known: #{bluebook.aggregates.map(&:hecks_name).sort.join(", ")}"
+                                 "known: #{aggregate_names(bluebook)}"
+    end
+
+    # :nodoc:
+    def aggregate_names(bluebook)
+      names = bluebook.aggregates.map(&:hecks_name)
+      names.sort.join(", ")
     end
 
     # The alias table CliRunner resolves against, for one bluebook.
@@ -125,11 +133,13 @@ module Hecks
     # :nodoc:
     def audited(request, tool)
       outcome = yield
-      record!(request.bluebook.name, tool: tool, verb: outcome[:verb], outcome: outcome, **audit_fields(request))
+      bluebook = request.bluebook
+      record!(bluebook.name, tool: tool, verb: outcome[:verb], outcome: outcome, **audit_fields(request))
       outcome.except(:verb)
     rescue *refusal_classes => e
       outcome = refused(e, summary: request.summary)
-      record!(request.bluebook&.name, tool: tool, outcome: outcome, **audit_fields(request))
+      asked_of = request.bluebook
+      record!(asked_of&.name, tool: tool, outcome: outcome, **audit_fields(request))
       outcome
     end
 

data/lib/hecks/switches.rb

@@ -0,0 +1,21 @@
+module Hecks
+  # The switches a test process can flip through its environment, read in one place so the
+  # runtime and the bluebook layer never read `ENV` themselves.
+  #
+  # Each turns a cache off for a child process that must boot uncached. A person ruling a cache
+  # out as the cause empties it instead, with `hecks test_suite_run.clear_caches!`.
+  #
+  # @example
+  #   Hecks::Switches.verdict_cache?  # => false under HECKS_VERDICT_CACHE=off
+  module Switches
+    module_function
+
+    # @return [Boolean] whether the syntax-boot table is cached on disk;
+    #   `HECKS_SYNTAX_BOOT_CACHE=off` turns it off
+    def syntax_boot_cache? = ENV["HECKS_SYNTAX_BOOT_CACHE"] != "off"
+
+    # @return [Boolean] whether meta-validator verdicts are cached on disk;
+    #   `HECKS_VERDICT_CACHE=off` turns it off
+    def verdict_cache? = ENV["HECKS_VERDICT_CACHE"] != "off"
+  end
+end

data/lib/hecks/tenancy/bluebook/tenancy.bluebook

@@ -45,15 +45,11 @@ Hecks.bluebook "Tenancy" do
     command "Register" do
       goal "Record that a tenant now exists, after its shape has been validated and its schema provisioned"
 
-      attribute :slug,   Slug
-      attribute :domain, DomainName
-      attribute :realm,  Realm
-      attribute :schema, Schema
-
-      sets :slug
-      sets :domain
-      sets :realm
-      sets :schema
+      attribute :slug,   Slug, sets: true
+      attribute :domain, DomainName, sets: true
+      attribute :realm,  Realm, sets: true
+      attribute :schema, Schema, sets: true
+
 
       emits "TenantRegistered"
     end

data/lib/hecks/text.rb

@@ -0,0 +1,57 @@
+module Hecks
+  # Plain-text readings the framework takes again and again: the first line of a message, a
+  # comma-separated list, whether a value says anything at all. Each pipeline is named here once,
+  # so a caller says what it wants instead of replaying how to get it.
+  module Text
+    # Any run of whitespace.
+    WHITESPACE = /\s+/
+
+    # A comma and the space around it, as in "a, b ,c".
+    COMMA = /\s*,\s*/
+
+    module_function
+
+    # The first line of `text`, stripped. Error messages put their sentence on the first line.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @return [String] the first line without surrounding whitespace, or `""` for no text
+    def first_line(text) = text.to_s.lines.first.to_s.strip
+
+    # The first line of `text` with only its line ending removed: a message's headline.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @return [String] the first line, its own spacing kept, or `""` for no text
+    def headline(text) = text.to_s.lines.first.to_s.chomp
+
+    # The last `count` lines of `text`, joined and stripped: the tail of a command's output.
+    #
+    # @param text [String, #to_s, nil] the text to read
+    # @param count [Integer] how many lines to keep
+    # @return [String] the kept lines, joined, without surrounding whitespace
+    def last_lines(text, count) = text.to_s.lines.last(count).join.strip
+
+    # Says whether `value` holds no text once whitespace is set aside.
+    #
+    # @param value [String, #to_s, nil] the value to read
+    # @return [Boolean] whether `value` is `nil`, empty or only whitespace
+    def blank?(value) = value.to_s.strip.empty?
+
+    # Splits a comma-separated value into its items, dropping empty ones.
+    #
+    # @param value [String, #to_s, nil] a list such as `"a, b,,c"`
+    # @return [Array<String>] the stripped, non-empty items, in order
+    def comma_list(value) = value.to_s.split(",").map(&:strip).reject(&:empty?)
+
+    # Joins the stripped, non-empty lines of `lines` back into one text.
+    #
+    # @param lines [Array<String>] the lines to keep
+    # @return [String] the non-blank lines, stripped, one per line
+    def compact_lines(lines) = lines.map(&:strip).reject(&:empty?).join("\n")
+
+    # The names of `items`, sorted and comma-joined: how a refusal lists what it would accept.
+    #
+    # @param items [Array<#name>] the things to name
+    # @return [String] their names, sorted, joined with ", "
+    def name_list(items) = items.map(&:name).sort.join(", ")
+  end
+end