hecks 5.0.0 → 7.0.0

data/lib/hecks/projector/cli_projector/command_specs.rb

@@ -6,6 +6,9 @@ module Hecks
       # The spec hash of each command, port operation, query and report: what the runner parses
       # a call against and what `--help` describes.
       module CommandSpecs
+        # The last `.segment` of a dotted name.
+        LAST_SEGMENT = /\.[^.]+\z/
+
         # The options that name the record a command acts on, before its own arguments.
         # `nil` (a creating command) takes none: there is no record yet.
         # Ports always pass `:aggregate`, since a port is declared on an aggregate.
@@ -49,10 +52,20 @@ module Hecks
         # What the command declares about itself, apart from its arguments.
         def command_facts(aggregate, command)
           { summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,
-            group: aggregate.hecks_name, internal: command.role.to_s == "System",
+            group: aggregate.hecks_name, internal: internal?(command), audience: command.audience,
+            formerly: aggregate.former_name,
             creates: command.creates? }
         end
 
+        # Whether the default listing leaves the command out. A declared audience decides: the
+        # listing is for a person. A command that declares none is a run's own bookkeeping when
+        # its role is `System`, else listed.
+        def internal?(command)
+          return command.role.to_s == "System" if command.audience.empty?
+
+          !command.audience.include?("person")
+        end
+
         # The receiver entries of a spec. `id=...` is still accepted for aggregate receivers but
         # hidden from help, which teaches only `to=...`.
         def receiver_facts(receiver)
@@ -86,7 +99,7 @@ module Hecks
         # `Dispatcher#dispatch` looks the head up as a port, so the wire name is
         # `Aggregate.Port.Operation`; the launcher name hides the port.
         def port_wire_name(bluebook, aggregate, port, operation)
-          [fqn(bluebook, aggregate, operation).sub(/\.[^.]+\z/, ""), port.name, operation.hecks_name].join(".")
+          [fqn(bluebook, aggregate, operation).sub(LAST_SEGMENT, ""), port.name, operation.hecks_name].join(".")
         end
 
         # Who issues a port operation, in the direction it runs.
@@ -106,11 +119,11 @@ module Hecks
           "Ask #{port.name} — answers #{operation.answers}, refuses #{operation.refuses}"
         end
 
-        # The conditions that refuse the command when they hold, in the chapter's own words: a
+        # The conditions that refuse the command when they hold, in the bluebook's own words: a
         # lifecycle state mismatch and a missing referenced record per `reference_to`.
         def refusals(command, holder)
           lifecycle_refusals(command, holder) +
-            command.attributes.select(&:reference?).map { |r| "no #{r.type.target_name} has that #{r.name}" }
+            command.attributes.select(&:reference?).map { |r| "no #{r.target_name} has that #{r.name}" }
         end
 
         # The refusal for a lifecycle state the command does not run from, or none.
@@ -118,9 +131,10 @@ module Hecks
           lifecycle = holder.lifecycle
           return [] unless lifecycle
 
-          froms = lifecycle.transitions.filter_map do |name, transition|
+          sources = lifecycle.transitions.filter_map do |name, transition|
             Array(transition.from) if name.to_s == command.hecks_name
-          end.flatten.uniq
+          end
+          froms = sources.flatten.uniq
           froms.empty? ? [] : ["#{lifecycle.field} is not #{froms.join(" or ")}"]
         end
 

data/lib/hecks/projector/cli_projector/completion.rb

@@ -0,0 +1,87 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # `hecks completion <shell>` (ADR 0163, plan step 7): the words a shell completes, read from
+      # the same listing the help prints, and the script that registers them. Nothing here is typed
+      # by hand: a renamed command or a new module reaches the completions with the next projection.
+      module Completion
+        # The shells a completion script is written for. PowerShell is not among them (step 48).
+        SHELLS = %w[bash zsh fish].freeze
+
+        # The words a completion offers: the first word of a line (modules, the everyday names and
+        # the launcher's own words), and per aggregate, its calls with the bang on commands.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules are offered
+        # @param cli [Hash] the projection (`:commands`, `:questions`)
+        # @param options [Hash] the listing's options, which decide the calls shown (`:everyday`)
+        # @return [Hash{Symbol => Object}] `:first` (the words of the first place), `:calls` (the
+        #   calls per aggregate name) and `:all` (every call, for a shell that filters by prefix)
+        def completion_words(bluebook, cli, options)
+          calls = shown_calls(cli, options).group_by { |spec| spec[:group] }
+                                           .transform_values { |specs| specs.map { |spec| label(spec) } }
+          { first: first_words(bluebook, options) + calls.keys.map { |name| "#{name}." },
+            calls: calls, all: calls.values.flatten }
+        end
+
+        # The script a shell sources to complete the words, registered for the program's first word.
+        #
+        # @param shell [String] one of `SHELLS`
+        # @param program [String] the launcher's name, such as `hecks`
+        # @param words [Hash] what `completion_words` returned
+        # @return [String, nil] the script, or nil for a shell this projection does not write
+        def completion_script(shell, program, words)
+          name = program.split.first
+          case shell
+          when "bash" then bash_script(name, words)
+          when "zsh" then zsh_script(name, words)
+          when "fish" then fish_script(name, words)
+          end
+        end
+
+        # The calls the audience is shown, internal ones left out.
+        def shown_calls(cli, options)
+          [cli[:commands], cli[:questions]].flat_map do |table|
+            CliAudience.audience_specs(table, options).values.reject { |spec| spec[:internal] }
+          end
+        end
+
+        # The module names, the everyday names and the launcher's own words.
+        def first_words(bluebook, options)
+          modules = bluebook.modules.map { |row| Naming.snake(row.name) }.uniq
+          modules + Array(options[:everyday]) + %w[search completion help --all --maintainer]
+        end
+
+        # A bash script: a function completing the current word, registered for the program.
+        def bash_script(name, words)
+          fn = "_#{name.tr("^A-Za-z0-9_", "_")}_complete"
+          lines = ["#{fn}() {", %(  local cur="${COMP_WORDS[COMP_CWORD]}"), "  COMPREPLY=()", %(  case "$cur" in)]
+          lines += words[:calls].map { |agg, calls| "    #{agg}.*) #{bash_reply(calls, "$cur")} ;;" }
+          lines += ["    *) #{bash_reply(words[:first], "$cur")} ;;", "  esac", "}", "complete -F #{fn} #{name}"]
+          "#{lines.join("\n")}\n"
+        end
+
+        # The bash assignment offering a list of words that start with the current one.
+        def bash_reply(list, cur)
+          %{COMPREPLY=( $(compgen -W '#{list.join(" ")}' -- "#{cur}") )}
+        end
+
+        # A zsh script: a function offering the same words through `compadd`.
+        def zsh_script(name, words)
+          lines = [
+            "_#{name.tr("^A-Za-z0-9_", "_")}() {", "  local cur=$words[CURRENT]", "  case $cur in"
+          ]
+          lines += words[:calls].map { |agg, calls| "    #{agg}.*) compadd -- #{calls.map { |c| "'#{c}'" }.join(" ")} ;;" }
+          lines += ["    *) compadd -- #{words[:first].map { |w| "'#{w}'" }.join(" ")} ;;", "  esac", "}"]
+          lines << "compdef _#{name.tr("^A-Za-z0-9_", "_")} #{name}"
+          "#{lines.join("\n")}\n"
+        end
+
+        # A fish script: every word offered for the program, fish filtering them by prefix.
+        def fish_script(name, words)
+          offered = (words[:first] + words[:all]).join(" ")
+          "complete -c #{name} -f -a '#{offered}'\n"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/everyday.rb

@@ -0,0 +1,40 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The lines the help opens with: the commands and queries a person types most, which the
+      # launcher setting names as `everyday`, each line the call to type (ADR 0163).
+      module Everyday
+        # The `everyday` section: a heading, then one row per named command or query the audience
+        # is shown, in the setting's order, each spelled in full. A name the audience is not shown,
+        # or that names nothing, is left out; nothing is listed for a newcomer, whose help lists
+        # only the newcomer commands.
+        #
+        # @param commands [Hash{String => Hash}] the command specs the audience is shown
+        # @param questions [Hash{String => Hash}] the query specs the audience is shown
+        # @param options [Hash] the projection's options; `:everyday` names the lines, `:only`
+        #   marks a newcomer's help
+        # @return [Array<String>] the section's lines, or none
+        def everyday_lines(commands, questions, options)
+          return [] if Array(options[:only]).any?
+
+          specs = Array(options[:everyday]).filter_map { |name| commands[name] || questions[name] }
+          return [] if specs.empty?
+
+          ["everyday:", *everyday_rows(specs), ""]
+        end
+
+        # How much of what a line does fits beside its call on one terminal line.
+        EVERYDAY_TEXT = 72
+
+        # One row per spec: its full call padded to the widest, then the first sentence of what it
+        # does, cut at a word to fit one line.
+        def everyday_rows(specs)
+          row = row_formatter(specs.to_h { |spec| [spec, label(spec, real: true)] }) do |spec|
+            CliAudience.clipped(first_sentence(spec[:summary]), EVERYDAY_TEXT)
+          end
+          specs.map { |spec| row.call(spec, "  ") }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/json_listing.rb

@@ -0,0 +1,77 @@
+require "json"
+require_relative "../../naming"
+
+module Hecks
+  module Projector
+    module CliProjector
+      # `hecks --json` and `hecks <module> --json` (ADR 0163, plan step 9): the same entries the
+      # help lists, as JSON, so the MCP door, the docs and scripts read one projection. Each entry
+      # is one command or query, with the call to type and the module it sits under.
+      module JsonListing
+        # The JSON document for the listing: one array of entries, in the order the help lists them.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules name each entry
+        # @param commands [Hash{Symbol => Hash}] the projected command specs
+        # @param questions [Hash{Symbol => Hash}] the projected query specs
+        # @param options [Hash{Symbol => Object}] the listing's options: `:all` includes the
+        #   internal entries; `:module` limits the entries to one module's name; `:everyday` names
+        #   the calls the everyday section lists
+        # @return [String] the JSON text
+        def json_listing(bluebook, commands, questions, options)
+          entries = [commands, questions].flat_map { |specs| json_entries(bluebook, specs, options) }
+          JSON.generate(entries)
+        end
+
+        # The entries of one table the audience is shown, internal ones only with `:all`, and
+        # limited to a module when one is named.
+        def json_entries(bluebook, specs, options)
+          shown = CliAudience.audience_specs(specs, options).reject { |_, spec| hidden?(spec, options) }
+          entries = shown.map { |key, spec| json_entry(bluebook, spec, key, options) }
+          entries.select { |entry| in_requested_module?(entry, options) }
+        end
+
+        # Whether an entry is internal and the listing leaves internal entries out.
+        def hidden?(spec, options)
+          spec[:internal] && !options[:all]
+        end
+
+        # Whether an entry sits in the module the listing was asked for, or in any when none was.
+        def in_requested_module?(entry, options)
+          options[:module].nil? || entry["module"] == Naming.snake(options[:module])
+        end
+
+        # One entry: its call, its qualified name, its verb, its kind, the module and aggregate it
+        # sits under, its description, its audience, and whether it is in the everyday section.
+        def json_entry(bluebook, spec, key, options)
+          call = label(spec)
+          {
+            "call"     => call,
+            "everyday" => Array(options[:everyday]).include?(key),
+            "module"   => group_name(bluebook, spec),
+            **entry_identity(spec),
+            **entry_flags(spec)
+          }
+        end
+
+        # What an entry is called: its call, qualified name, verb, kind and aggregate.
+        def entry_identity(spec)
+          {
+            "name"      => spec[:command],
+            "verb"      => spec[:short].to_s,
+            "kind"      => spec[:kind].to_s,
+            "aggregate" => spec[:group]
+          }
+        end
+
+        # What an entry says about itself: its description, audience and whether it is internal.
+        def entry_flags(spec)
+          {
+            "description" => spec[:summary].to_s,
+            "audience"    => Array(spec[:audience]).map(&:to_s),
+            "internal"    => spec[:internal] ? true : false
+          }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/listing.rb

@@ -33,7 +33,8 @@ module Hecks
 
         # A lambda that renders one spec at an indent: its name padded to the widest, then its text.
         def row_formatter(named, &)
-          width = named.values.map(&:length).max.to_i
+          lengths = named.values.map(&:length)
+          width = lengths.max.to_i
           ->(spec, indent) { "#{indent}#{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
         end
 
@@ -53,20 +54,30 @@ module Hecks
 
         # The aggregate's own name as a heading: the prefix of every call to the lines under it.
         def heading(group)
-          "#{Naming.snake(group)}:"
+          "#{group}:"
+        end
+
+        # A launcher name in the bluebook's verb form: the aggregate as the bluebook spells it, then
+        # the rest of the name (`send_train.board` as `SendTrain.board`). A name that does not start
+        # with its aggregate, such as a short name a bluebook gave a command, is left as it is.
+        def verb_form(spec, name)
+          group = spec[:group]
+          return name unless group && name.start_with?("#{Naming.snake(group)}.")
+
+          "#{group}#{name.delete_prefix(Naming.snake(group))}"
         end
 
         # A spec's name as listed: under its aggregate's heading the aggregate prefix is left out.
-        # A command the chapter gives a short name (`mcp`) is listed by its real name, so the
+        # A command the bluebook gives a short name (`mcp`) is listed by its real name, so the
         # heading and the line still spell a call; `alias_note` says the short name.
         def entry_name(spec, grouped)
           name = label(spec, real: true)
           return name unless grouped && spec[:group]
 
-          name.delete_prefix("#{Naming.snake(spec[:group])}.")
+          name.delete_prefix("#{spec[:group]}.")
         end
 
-        # " (also: mcp!)" for a spec the chapter gave a short name, else nothing. A short name that
+        # " (also: mcp!)" for a spec the bluebook gave a short name, else nothing. A short name that
         # is only the command's own name (`init` for `launch.init`) is already in the line.
         def alias_note(spec)
           return "" if spec[:short_was].nil? || spec[:short_was].split(".").last == spec[:short]
@@ -74,10 +85,11 @@ module Hecks
           " (also: #{label(spec)})"
         end
 
-        # A command is written with the `!` that marks it; a query without one.
-        # With `real:`, a short name the chapter gave it gives way to the name it was given for.
+        # A command is written with the `!` that marks it; a query without one. Both are in the
+        # verb form. With `real:`, a short name the bluebook gave it gives way to the name it was
+        # given for.
         def label(spec, real: false)
-          name = real && spec.key?(:short_was) ? spec[:short_was] : spec[:short]
+          name = verb_form(spec, real && spec.key?(:short_was) ? spec[:short_was] : spec[:short])
           spec[:kind] == :command ? "#{name}!" : name
         end
 

data/lib/hecks/projector/cli_projector/modules.rb

@@ -0,0 +1,39 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The help of one module of a bluebook (ADR 0163): the commands and queries of the
+      # aggregates the module groups, listed under the module's name and vision.
+      module Modules
+        # The module a word names, in the bluebook's own spelling: `deliver` for `Deliver`.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules are searched
+        # @param word [String, nil] a word of the command line
+        # @return [String, nil] the module's name, or nil when the bluebook has none by that word
+        def module_named(bluebook, word)
+          module_names(bluebook).find { |name| Naming.snake(name) == word }
+        end
+
+        # Each module's name once, in declaration order.
+        def module_names(bluebook)
+          bluebook.modules.map(&:name).uniq
+        end
+
+        # The specs of the aggregates `name` groups; every spec when no module is asked for.
+        def in_module(bluebook, specs, name)
+          return specs unless name
+
+          members = bluebook.modules.select { |row| row.name == name }.map(&:aggregate)
+          specs.select { |_, spec| members.include?(spec[:group]) }
+        end
+
+        # A module's heading: its word and its vision, then the two ways to call what it lists.
+        def module_header(bluebook, name, program)
+          vision = bluebook.modules.find { |row| row.name == name }.vision
+          ["#{Naming.snake(name)} — #{vision}", "",
+           "  #{program} <Aggregate.command>! [name=value …]    do something",
+           "  #{program} <Aggregate.query> [name=value …]       read something", ""]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/option_specs.rb

@@ -72,7 +72,7 @@ module Hecks
         # The option of an attribute that references another record, which is given by its id.
         def reference_option(attribute)
           { path: attribute.name.to_s, type: "String", required: !attribute.optional?,
-            note: "id of a #{attribute.type.target_name}" }
+            note: "id of a #{attribute.target_name}" }
         end
 
         # A `list_of` scalar carries `list: true, words: true`: the launcher reads a comma-separated

data/lib/hecks/projector/cli_projector/query_specs.rb

@@ -43,12 +43,13 @@ module Hecks
         # The fields that are the aggregate's own bookkeeping: its identity and its
         # lifecycle status.
         def own_fields(aggregate)
-          Array(aggregate.identified_by).map(&:to_s) + [aggregate.lifecycle&.field.to_s]
+          Array(aggregate.identified_by).map(&:to_s) + [aggregate.lifecycle_field&.to_s]
         end
 
         # The spec of one query of an aggregate or of one of its entities.
         def query_spec(bluebook, aggregate, entity, query)
           { command: fqn(bluebook, aggregate, query, entity), kind: :query, group: aggregate.hecks_name,
+            formerly: aggregate.former_name,
             internal: entity.nil? && bookkeeping_query?(aggregate, query),
             summary: query.description, arguments: query_arguments(query, aggregate, entity),
             returns: query.returns }

data/lib/hecks/projector/cli_projector/renames.rb

@@ -0,0 +1,58 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # The launcher's rename table: the old command names a bluebook's `launcher` setting lists as
+      # `renamed`, each mapped to the command it became. An old spelling resolves to the new command
+      # and the launcher prints the new spelling once; an entry may also translate old argument names.
+      #
+      # The table resolves through 8.0; its removal is recorded in docs/compatibility.md.
+      module Renames
+        # The old spellings a `renamed` table maps to the commands they became, in the snake form
+        # the name index uses.
+        #
+        # @param commands [Hash{String => Hash}] the projected commands, keyed by snake-form name
+        # @param renamed [Hash{String => String, Hash}, nil] old name to new name, or to a hash
+        #   with `to:` and `arguments:` (old argument name to new)
+        # @return [Hash{Symbol => Hash{String => String}}] `:command` and `:question`, each mapping an
+        #   old spelling to the name it became
+        # @raise [Bluebook::DSL::Malformed] if an entry names no projected command
+        def renamed_aliases(commands, questions, renamed)
+          Hash(renamed).each_with_object({ command: {}, question: {} }) do |(old, target), map|
+            to = renamed_target(target)
+            space = renamed_space(commands, questions, to, old)
+            map[space][old.to_s] = to
+          end
+        end
+
+        # The namespace a renamed name's target belongs to: a command, or a query when no command
+        # has that name.
+        #
+        # @raise [Bluebook::DSL::Malformed] if the target is neither a command nor a query
+        def renamed_space(commands, questions, to, old)
+          return :command if commands.key?(to)
+          return :question if questions.key?(to)
+
+          raise Bluebook::DSL::Malformed, "renamed #{old.inspect} names no command or query"
+        end
+
+        # The argument renames of each old spelling, read by the launcher to translate `old=value`.
+        #
+        # @return [Hash{String => Hash{String => String}}] old spelling to its argument renames
+        def renamed_arguments(renamed)
+          Hash(renamed).each_with_object({}) do |(old, target), map|
+            map[old.to_s] = renamed_entry(target)[:arguments].to_h.transform_keys(&:to_s)
+          end
+        end
+
+        # The new command name an entry names.
+        def renamed_target(target) = renamed_entry(target)[:to].to_s
+
+        # An entry as a hash with symbol keys: a bare string names the command, and a hash gives
+        # `to:` and, optionally, `arguments:`.
+        def renamed_entry(target)
+          target.is_a?(Hash) ? target.transform_keys(&:to_sym) : { to: target }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/search.rb

@@ -0,0 +1,74 @@
+module Hecks
+  module Projector
+    module CliProjector
+      # `hecks search <word>` (ADR 0163, plan step 20): the commands and queries whose call or
+      # description holds a word, each as the call to type, grouped by module when the bluebook
+      # declares one and by aggregate otherwise. It reads the listing's own specs and labels, so
+      # a renamed command is found under its new name without a second index.
+      module Search
+        # The lines answering a search, or nil when nothing matches.
+        #
+        # @param bluebook [Bluebook::Declaration] the bluebook whose modules group the hits
+        # @param commands [Hash{Symbol => Hash}] the projected command specs
+        # @param questions [Hash{Symbol => Hash}] the projected query specs
+        # @param options [Hash{Symbol => Object}] the listing's options; `:all` includes the
+        #   internal commands and queries, as `--all` does
+        # @param word [String] the word to find, matched case-insensitively
+        # @return [Array<String>, nil] the lines to print, or nil when no command or query matches
+        def search_lines(bluebook, commands, questions, options, word)
+          hits = [commands, questions].flat_map { |specs| hits_in(specs, options, word.downcase) }
+          return if hits.empty?
+
+          ranked_lines(bluebook, hits)
+        end
+
+        # The hits in rank order, name matches first, each rank under its module or aggregate.
+        def ranked_lines(bluebook, hits)
+          width = hits.map { |hit| label(hit[:spec]).length }.max
+          hits.sort_by { |hit| [hit[:rank], label(hit[:spec])] }
+              .partition { |hit| hit[:rank].zero? }
+              .flat_map { |part| grouped_lines(bluebook, part, width) }
+        end
+
+        # The hits of one rank, under a heading per module or aggregate, in the order they appear.
+        def grouped_lines(bluebook, hits, width)
+          hits.group_by { |hit| group_name(bluebook, hit[:spec]) }.flat_map do |group, members|
+            ["#{group}:", *members.map { |hit| hit_line(hit[:spec], width) }]
+          end
+        end
+
+        # The matching specs of one table with the rank of each: 0 for a match on the call,
+        # 1 for a match on the description only. Internal specs stay out unless `:all` is given.
+        def hits_in(specs, options, needle)
+          CliAudience.audience_specs(specs, options).values.filter_map do |spec|
+            next if spec[:internal] && !options[:all]
+
+            rank = rank_of(spec, needle)
+            { spec: spec, rank: rank } if rank
+          end
+        end
+
+        # Where a spec matches the needle: its call (0), its description (1), or nowhere (nil).
+        def rank_of(spec, needle)
+          return 0 if label(spec).downcase.include?(needle)
+          return 1 if spec[:summary].to_s.downcase.include?(needle)
+
+          nil
+        end
+
+        # The heading a hit sits under: its module's name when a module of the bluebook groups its
+        # aggregate, else the aggregate's own name.
+        def group_name(bluebook, spec)
+          row = bluebook.modules.find { |module_row| module_row.aggregate == spec[:group] }
+          row ? Naming.snake(row.name) : spec[:group]
+        end
+
+        # One hit: the call to type, padded to the widest, then what it does in one sentence.
+        def hit_line(spec, width)
+          text = spec[:kind] == :command ? spec[:summary].to_s : first_sentence(spec[:summary].to_s)
+          "  #{label(spec).ljust(width)}  #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_projector/usage.rb

@@ -1,10 +1,14 @@
 require_relative "../../naming"
+require_relative "../../adapters/driving/exit_status"
 
 module Hecks
   module Projector
     module CliProjector
       # The usage text of a projection: the command and query tables, or one command's help.
       module Usage
+        # The space after a sentence's closing full stop.
+        SENTENCE_BREAK = /(?<=\.)\s/
+
         # Renders the full command/question table, or one command's `--help` text when
         # `options[:command]` names one.
         def usage(bluebook, commands, questions, options)
@@ -21,7 +25,7 @@ module Hecks
           return unless only
 
           spec = help_spec(only, commands, questions, options[:ask])
-          command_help(program, spec[:short], spec, ask: options[:ask]) if spec
+          command_help(program, verb_form(spec, spec[:short]), spec, ask: options[:ask]) if spec
         end
 
         # `ask` picks the namespace when both hold the name; without it a
@@ -32,12 +36,15 @@ module Hecks
           pool[key] || questions[key]
         end
 
-        # The whole help: the two tables, the chapters, then the hints.
+        # The whole help: the everyday lines, the two tables, the bluebooks, then the hints.
         def full_usage(bluebook, commands, questions, options, program)
-          shown = [commands, questions].map { |specs| CliAudience.audience_specs(specs, options) }
-          [usage_header(bluebook, program),
+          shown = [commands, questions].map do |specs|
+            in_module(bluebook, CliAudience.audience_specs(specs, options), options[:module])
+          end
+          [header_for(bluebook, program, options[:module]),
+           everyday_lines(*shown, options),
            tables(*shown, all: options[:all], notes: aggregate_notes(bluebook)),
-           CliAudience.chapter_lines(program, options[:chapters]),
+           CliAudience.bluebook_lines(program, options[:declarations]),
            usage_footer(program, shown, options, left_out(commands, questions, shown))].flatten(1).join("\n")
         end
 
@@ -46,9 +53,14 @@ module Hecks
           commands.size + questions.size - shown.sum(&:size)
         end
 
-        # The chapter's vision and the two ways to call it.
+        # The heading of the help: the bluebook's, or the module's when one is asked for.
+        def header_for(bluebook, program, module_name)
+          module_name ? module_header(bluebook, module_name, program) : usage_header(bluebook, program)
+        end
+
+        # The bluebook's vision, the release of the gem this launcher runs, and the two ways to call it.
         def usage_header(bluebook, program)
-          ["#{bluebook.name} — #{bluebook.vision}", "",
+          ["#{bluebook.name} — #{bluebook.vision}", "  hecks #{Hecks::VERSION}", "",
            "  #{program} <command>! [name=value …]       do something",
            "  #{program} query <query> [name=value …]    read something", ""]
         end
@@ -63,7 +75,15 @@ module Hecks
 
           out.concat(all_hint(program, *shown)) unless options[:all]
           out.concat(CliAudience.maintainer_hint(program, hidden_count))
-          out << "  a command is called with its aggregate — #{example_qualified(shown.first)}"
+          out.concat(closing_lines(shown, options))
+        end
+
+        # The example call and, for a launcher that opted in, the line naming the three exit
+        # statuses. A launcher that did not opt in keeps the text every earlier generator wrote,
+        # which exits 1 for every line it could not read, so it claims nothing.
+        def closing_lines(shown, options)
+          lines = ["  a command is called with its aggregate — #{example_qualified(shown.first)}"]
+          options[:opted] ? lines << "  #{Adapters::Driving::ExitStatus::HELP_LINE}" : lines
         end
 
         # The commands table then the queries table.
@@ -96,15 +116,16 @@ module Hecks
                   .reject { |_, note| note.empty? }
         end
 
-        # An example call, `aggregate.command!`, from the first command, or `""` when there is none.
+        # An example call, `Aggregate.command!`, from the first command, or `""` when there is none.
         def example_qualified(commands)
-          name = commands.keys.first
-          name ? "#{name}!" : ""
+          spec = commands.values.first
+          spec ? label(spec, real: true) : ""
         end
 
         # The command table wants a query description's first sentence; `--help` prints all.
         def first_sentence(text)
-          text.to_s.split(/(?<=\.)\s/).first.to_s
+          sentences = text.to_s.split(SENTENCE_BREAK)
+          sentences.first.to_s
         end
       end
     end