hecks 3.0.4 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90a718a197fae0287e4fe16033540bf625166bc31bfb3482e0752d1039a2a949
-  data.tar.gz: 15fe27abd9a488dfe4f579118f8e8ffbea1302b956ee36fbd2b9475eb3b88429
+  metadata.gz: 29694d3639f1ad69a3d0a81bf4e6494c5a6d60a88ca9897af3a01224944d654e
+  data.tar.gz: b9fb1376266fe98b2d09c6127bbbbe3a954c11e9441c3f01976e54f44b63eaf7
 SHA512:
-  metadata.gz: d74d07807e22e8899c041adfa96d799b5eb47713a0dec6c05bbb9e61a579a32a35da890b67aaf876b1ba5182e0961a112f370e0e04adcf2719f8ae57a50cfd45
-  data.tar.gz: 11e85c77dc6a4f5d34ec3acd54e41873be8d03b980e4ef97a8d0d7c9da4b63ecfc2b04e2a1322f8c1536ad1d58f8f85f50df2ca58f3d6fea44126cb871c05b0d
+  metadata.gz: 6eea28ed2426948aeca13df88967f06a5d64acf29dbb376a16b53d82367e90383f3646928ee4940ff9d93969ea7721ed29fb4467096eb8a2b88bc14f7f7ede47
+  data.tar.gz: 52d5f117ce1b1bae946f939dad3c73567a44c5c466257c37cbaf5bb7bcecb0cb3a3ea92e9c41b3edde78efbdb674669d08f56305287f46313c1cb4ce813d3042

data/exe/hecks

@@ -2,12 +2,12 @@
 
 # Hecks's command line — GENERATED by hecks project_cli. Do not edit.
 #
-# A launcher, not a CLI: the verbs, their arguments and their refusals are
+# A launcher, not a CLI: the commands, their arguments and their refusals are
 # projected from the bluebook beside it every time this runs, so a change
 # to the chapter shows up here without re-minting anything.
 #
-#   exe/hecks                  every verb, and every question
-#   exe/hecks <verb> --help    what it wants, and how it refuses
+#   exe/hecks                  every command, and every question
+#   exe/hecks <command> --help    what it wants, and how it refuses
 
 Encoding.default_external = Encoding::UTF_8
 Encoding.default_internal = Encoding::UTF_8
@@ -21,10 +21,17 @@ if LEGACY.include?(ARGV.first)
   exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
 end
 
+# These commands keep nothing worth a database, so they run on Memory unless told otherwise.
+# A person is at them: they wait for their result, say why when they are refused, and print
+# no record when they end well.
+MEMORY_COMMANDS = %w[console init].freeze
+ENV["HECKS_ENVIRONMENT"] ||= "memory" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
+
 require "hecks"
 
 # Usage is answered from the projected chapter alone: no adapter is bound and no
-# database is opened. Only a line that runs a verb boots the domain,
+# database is opened. Only a line that runs a command boots the domain,
 # and it boots from what the usage check already loaded.
 domain = File.expand_path("../lib/hecks/hecks", __dir__)
 program = "hecks"
@@ -39,7 +46,7 @@ text, status, reason = Hecks::Doors::CliRunner.usage(
 )
 unless text
   runtime = begin
-    Hecks.boot_described(described, install_doors: false)
+    Hecks::Doors::LauncherOptions.quietly(hold: MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))) { Hecks.boot_described(described, install_doors: false) }
   rescue StandardError => e
     abort "cannot open Hecks: #{e.message.lines.first.strip}"
   end
@@ -53,8 +60,19 @@ end
 # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
 # either way, and says why on stderr.
 if reason
-  puts text
-  warn reason
+  if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
+    why = begin
+      require "json"
+      JSON.parse(text).dig("state", "refusal", "value")
+    rescue JSON::ParserError
+      nil
+    end
+    warn(why ? why.sub(/\A(\w+::)+\w+: /, "") : reason)
+  else
+    puts text
+    warn reason
+  end
   exit status
 end
+exit 0 if status.zero? && MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
 status.zero? ? puts(text) : abort(text)

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -7,7 +7,7 @@ module Hecks
       # Runtime::RemoteDispatcher's writes: one Lambda invoke, one JSON round trip.
       #
       # The function name defaults to `"hecks-#{domain.downcase}"`, matching
-      # `hecks deploy project`'s `stack_name` computation. A domain whose stack
+      # `hecks deploy recipe.project`'s `stack_name` computation. A domain whose stack
       # name doesn't follow that pattern must pass `function` explicitly, via
       # a `.world`'s `persisted_by("Lambda")`/`dispatched_by("Lambda")` block.
       class Client

data/lib/hecks/adapters/driven/lambda.rb

@@ -38,7 +38,7 @@ module Hecks
         function = setting(settings, :function, nil)
         # `domain` only prefixes the instances lookup; the function to call is named by
         # DOMAIN_NAME (set in a deployed Lambda, where root is always /var/task), else by
-        # root's basename, which matches hecks deploy project's stack name on a local boot.
+        # root's basename, which matches hecks deploy recipe.project's stack name on a local boot.
         function_domain = ENV["DOMAIN_NAME"] || (root ? File.basename(root) : domain)
         @client = Client.new(domain: function_domain, region: region, function: function)
         @prefix = "#{domain}::#{aggregate.hecks_name}#"

data/lib/hecks/adapters/driven/tenant_provisioner.rb

@@ -5,8 +5,8 @@ require "fileutils"
 module Hecks
   module Adapters
     # The imperative half of tenant provisioning, behind `Deploy::Tenant.port
-    # "TenantProvisioning"`, for `Tenant.Provision` and for hecks deploy provision; booting the
-    # domain and its capability gate stay in hecks deploy provision.
+    # "TenantProvisioning"`, for `Tenant.Provision` and for hecks deploy tenant.provision; booting
+    # the domain and its capability gate stay in hecks deploy tenant.provision.
     class TenantProvisioner
       # Raised when a value is outside its allow-list or the overlay path leaves `environments/`.
       class Refused < ArgumentError; end

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -3,7 +3,7 @@ module Hecks
   module Bluebook
     module DSL
       # Parses a `.hecksagon` file's DSL block into a Hecksagon: a domain's adapter bindings,
-      # framework/vendored attachments and subscriptions — wiring, not part of the bluebook.
+      # attachments and subscriptions — wiring, not part of the bluebook.
       class HecksagonBuilder
         GRAMMAR_CONTEXT = "Hecksagon".freeze
 
@@ -57,20 +57,22 @@ module Hecks
           end
         end
 
-        attr_reader :binds, :subscriptions, :framework_members, :vendored_bluebooks, :attached_chapters
+        # The release that drops the deprecated spellings of `attaches`; kept in step with
+        # `Hecks::Doors::REMOVAL`, which this file cannot require.
+        REMOVAL = "3.2.0".freeze
+
+        attr_reader :binds, :subscriptions, :attachments
 
         def initialize(domain)
           @domain             = domain
           @binds              = []
           @subscriptions      = []
-          @framework_members  = []
-          @vendored_bluebooks = []
-          @attached_chapters  = []
+          @attachments        = []
           @bounded            = false
           @translates         = []
         end
 
-        # Marks this chapter as a bounded context; framework/vendored attachments set it too.
+        # Marks this chapter as a bounded context; an attachment marks its chapter bounded too.
         # Must declare at least one `translates` ACL or boot refuses.
         def bounded
           @bounded = true
@@ -79,35 +81,37 @@ module Hecks
         # Subscribes to an event from outside this domain's own bluebook.
         def subscribe(event) = @subscriptions << event.to_s
 
-        # Attaches a framework member (e.g. Governance) and loads it into the current registry.
+        # Attaches a chapter by name and loads it into the current registry, marked bounded.
+        #
+        # Without `from:` the name is a chapter the gem carries (a framework member such as
+        # Governance, or a language chapter such as Deploy) with the ports and adapters it
+        # ships. `from: :vendor` loads `vendor/embryonaut_bluebooks/<name>/bluebook` instead,
+        # and is never a fallback for a misspelt gem name.
+        #
+        # @param name [String, Symbol] a gem chapter's name or a vendored package's directory name
+        # @param from [Symbol, nil] `:vendor` for a vendored package, nil for a gem chapter
+        # @raise [Runtime::WiringError] if the name is unknown, or `from:` names another source
+        def attaches(name, from: nil)
+          unless [nil, :vendor].include?(from)
+            raise Runtime::WiringError,
+                  "attaches #{name.to_s.inspect}, from: #{from.inspect} — `from:` takes only :vendor"
+          end
+
+          from == :vendor ? attach_vendored(name) : attach_gem(name)
+        end
+
+        # The deprecated spelling of `attaches "Name"` for a framework member.
         def uses_framework(name)
-          @framework_members << name.to_s
-          Hecks::Framework.load!(name)
-          # Marks the framework member as bounded; the consumer's own hecksagon is the
-          # anti-corruption layer.
+          deprecated_word("uses_framework", "attaches #{name.to_s.inspect}")
+          @attachments << Attachment.new(name: name.to_s, source: :gem)
+          self.class.with_real_modules { Hecks::Framework.load!(name) }
           Hecks.current_registry&.mark_bounded(name.to_s)
         end
 
-        # Attaches a vendored embryonaut bluebook to this domain and loads its files into the
-        # registry. Recorded separately from @framework_members, which is load-bearing for
-        # governance checks.
+        # The deprecated spelling of `attaches "name", from: :vendor`.
         def uses_embryonaut_bluebook(name)
-          @vendored_bluebooks << name.to_s
-          Hecks::EmbryonautBluebook.load!(name)
-          # Marks the chapter bounded, same as `uses_framework`; the directory name Pascal-cases
-          # to the chapter name (`"membership"` → `Membership`).
-          Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
-        end
-
-        # Attaches a chapter the gem carries (the language, Expression, Tenancy, Deploy,
-        # QualityControl) by name and loads its files into the registry, with the ports and
-        # adapters it ships. Marked bounded like a framework member, since this hecksagon is its
-        # anti-corruption layer.
-        def attaches(name)
-          require_relative "../../chapters"
-          @attached_chapters << name.to_s
-          self.class.with_real_modules { Hecks::Chapters.load!(name) }
-          Hecks.current_registry&.mark_bounded(name.to_s)
+          deprecated_word("uses_embryonaut_bluebook", "attaches #{name.to_s.inspect}, from: :vendor")
+          attach_vendored(name)
         end
 
         # Declares a port at the hecksagon's root — the chapter as a whole, not one aggregate.
@@ -145,9 +149,32 @@ module Hecks
         # No ungoverned-role check here — it runs once on the merged result at verify! time.
         def build
           Hecksagon.new(domain: @domain, binds: @binds, subscriptions: @subscriptions,
-                        framework_members: @framework_members, vendored_bluebooks: @vendored_bluebooks,
-                        attached_chapters: @attached_chapters, bounded: @bounded, translates: @translates)
+                        attachments: @attachments, bounded: @bounded, translates: @translates)
+        end
+
+        # Loads a chapter the gem carries and records it as attached from the gem.
+        def attach_gem(name)
+          require_relative "../../chapters"
+          @attachments << Attachment.new(name: name.to_s, source: :gem)
+          self.class.with_real_modules { Hecks::Chapters.attach!(name) }
+          Hecks.current_registry&.mark_bounded(name.to_s)
+        end
+        private :attach_gem
+
+        # Loads a vendored package and records it as attached from `vendor/`. The directory name
+        # Pascal-cases to the chapter name (`"membership"` becomes `Membership`).
+        def attach_vendored(name)
+          @attachments << Attachment.new(name: name.to_s, source: :vendor)
+          Hecks::EmbryonautBluebook.load!(name)
+          Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
+        end
+        private :attach_vendored
+
+        # Tells the author that a word is going away.
+        def deprecated_word(word, instead)
+          warn "[hecks] `#{word}` is deprecated and is removed in #{REMOVAL}; use `#{instead}`"
         end
+        private :deprecated_word
 
         # Records any verb the grammar doesn't own as a domain-wide default bind, e.g. bare
         # `persisted_by "Heki"` at the top of a block, applied unless an aggregate overrides it.

data/lib/hecks/bluebook/hexagon.rb

@@ -20,6 +20,23 @@ module Hecks
       def aggregate_name = Naming.demodulise(aggregate)
     end
 
+    # One chapter a hecksagon attaches, with where it was found.
+    #
+    # `source` is `:gem` for a chapter the gem carries (a framework member such as Governance,
+    # or a language chapter such as Deploy) and `:vendor` for a package vendored into the
+    # consuming project, whose `name` is the package's directory name (`"membership"`).
+    Attachment = Struct.new(:name, :source, keyword_init: true) do
+      # @return [Boolean] whether the chapter is a vendored package
+      def vendor? = source == :vendor
+
+      # @return [String] the chapter's name in the registry: a gem chapter's own name, a
+      #   vendored package's directory name in Pascal case
+      def chapter_name = vendor? ? Naming.pascal(name) : name
+
+      # @return [Hash{Symbol => String}] the attachment as plain data
+      def to_h = { name: name.to_s, source: source.to_s }
+    end
+
     # The built form of a `.hecksagon` file, produced by `DSL::HecksagonBuilder`.
     # `Behaviour::Hecksagon` supplies the bind lookups; this class holds the declared data.
     class Hecksagon
@@ -27,39 +44,31 @@ module Hecks
       include Behaviour::Hecksagon
 
       emits_ir(
-        domain:             :domain,
-        binds:              many(:binds),
-        subscriptions:      -> { subscriptions.map(&:to_s) },
-        framework_members:  -> { framework_members.map(&:to_s) },
-        vendored_bluebooks: -> { vendored_bluebooks.map(&:to_s) },
-        attached_chapters:  -> { attached_chapters.map(&:to_s) },
-        bounded:            :bounded?,
-        translates:         -> { translates.map(&:to_s) }
+        domain:        :domain,
+        binds:         many(:binds),
+        subscriptions: -> { subscriptions.map(&:to_s) },
+        attachments:   -> { attachments.map(&:to_h) },
+        bounded:       :bounded?,
+        translates:    -> { translates.map(&:to_s) }
       )
 
-      attr_reader :domain, :binds, :subscriptions, :framework_members, :vendored_bluebooks,
-                  :attached_chapters, :translates
+      attr_reader :domain, :binds, :subscriptions, :attachments, :translates
 
       # @param domain [String, Symbol] the domain this hecksagon wires
       # @param binds [Array<Bluebook::Bind>] the declared adapter binds
       # @param subscriptions [Array<String, Symbol>] the external events this domain
       #   subscribes to
-      # @param framework_members [Array<String, Symbol>] attached framework members (`Governance`)
-      # @param vendored_bluebooks [Array<String, Symbol>] the vendored embryonaut
-      #   bluebook package names this domain attaches
-      # @param attached_chapters [Array<String, Symbol>] chapters the gem carries, attached by name
+      # @param attachments [Array<Bluebook::Attachment>] every chapter this hecksagon attaches,
+      #   each with its source (`:gem` or `:vendor`)
       # @param bounded [Boolean] whether this chapter is an explicit bounded context
-      #   (consumer-owned; `uses_framework` / `uses_embryonaut_bluebook` mark
-      #   attached chapters bounded on the registry instead)
+      #   (consumer-owned; `attaches` marks attached chapters bounded on the registry instead)
       # @param translates [Array<String>] names of `translates` ACL blocks declared here
-      def initialize(domain:, binds: [], subscriptions: [], framework_members: [],
-                     vendored_bluebooks: [], attached_chapters: [], bounded: false, translates: [])
+      def initialize(domain:, binds: [], subscriptions: [], attachments: [], bounded: false,
+                     translates: [])
         @domain             = domain.to_s
         @binds              = binds
         @subscriptions      = subscriptions
-        @framework_members  = framework_members
-        @vendored_bluebooks = vendored_bluebooks
-        @attached_chapters  = attached_chapters
+        @attachments        = attachments
         @bounded            = bounded ? true : false
         @translates         = Array(translates).map(&:to_s)
       end
@@ -69,11 +78,22 @@ module Hecks
       # @return [Boolean] whether `bounded` was declared on this block
       def bounded? = @bounded
 
-      # Every chapter this hecksagon brings into its domain's registry: framework members and
-      # attached chapters alike, which resolve the same way.
+      # Every chapter this hecksagon brings into its domain's registry, gem and vendored alike.
+      #
+      # @return [Array<String>] the chapters' names as the registry holds them, in the order
+      #   they were attached
+      def member_chapters = attachments.map(&:chapter_name)
+
+      # Says whether this hecksagon attaches a chapter, whatever its source.
+      #
+      # @param chapter [String, Symbol] a chapter's name as the registry holds it
+      # @return [Boolean] whether that chapter is attached here
+      def attaches?(chapter) = member_chapters.include?(chapter.to_s)
+
+      # The vendored packages this hecksagon attaches.
       #
-      # @return [Array<String>] the chapters' names, framework members first
-      def member_chapters = (framework_members + attached_chapters).map(&:to_s)
+      # @return [Array<String>] their directory names, in the order they were attached
+      def vendored_packages = attachments.select(&:vendor?).map { |attachment| attachment.name.to_s }
     end
 
     # The built form of a `.world` file, produced by `DSL::WorldBuilder`.

data/lib/hecks/bluebook/model_check.rb

@@ -27,7 +27,7 @@ module Hecks
       # @param hecksagon [Bluebook::Hecksagon, nil] this bluebook's own sibling wiring
       #   file, if the caller loaded one
       # @param known_domains [Set<String>, nil] every bluebook/hecksagon name booted
-      #   anywhere in this corpus scan, checked to catch a typo'd across/uses_framework target
+      #   anywhere in this corpus scan, checked to catch a typo'd across/attaches target
       # @param global_emitted_events [Set<String>, nil] every event emitted anywhere in
       #   the corpus, checked as a fallback so a translates reaction isn't flagged deaf
       # @param profile [Symbol, nil] :client adds ClientProfile's error findings
@@ -371,7 +371,7 @@ module Hecks
         findings
       end
 
-      # `uses_framework` is a Shared Kernel relationship (X merges in, no boundary);
+      # `attaches` is a Shared Kernel relationship (X merges in, no boundary);
       # `across` is Customer/Supplier (real cross-Lambda RPC). This checks the choice
       # between them instead of leaving it as an unenforced comment. (ADR 0025)
       def cross_domain_policy_findings(policy, hecksagon, known_domains)
@@ -382,13 +382,13 @@ module Hecks
         target = policy.target_domain
         findings = []
 
-        if hecksagon.framework_members.include?(target)
+        if hecksagon.attaches?(target)
           # Shared Kernel and Customer/Supplier are mutually exclusive claims about
           # the same target — declaring both means either a pointless RPC to a
-          # domain already local, or a uses_framework that isn't doing its job.
+          # domain already local, or an attaches that isn't doing its job.
           findings << Finding.new(kind: :contradictory_relationship, severity: :error, subject: policy.name,
                                   message: "across #{target.inspect} dispatches over RPC (Customer/Supplier), " \
-                                           "but this hecksagon also uses_framework #{target.inspect} (Shared " \
+                                           "but this hecksagon also attaches #{target.inspect} (Shared " \
                                            "Kernel) — #{target} is already loaded in-process here, so the two " \
                                            "relationship declarations contradict each other for the same " \
                                            "target domain")
@@ -399,7 +399,7 @@ module Hecks
                                   message: "across #{target.inspect} declares a Customer/Supplier " \
                                            "relationship, but nothing in this hecksagon records the " \
                                            "expectation — add subscribe \"#{target}.SomeEvent\" for what " \
-                                           "you expect back from it, or uses_framework #{target.inspect} to " \
+                                           "you expect back from it, or attaches #{target.inspect} to " \
                                            "attach it in-process instead")
         end
 
@@ -426,7 +426,7 @@ module Hecks
         reached = []
         reached << "#{target} is a domain this corpus boots" if known_domains&.include?(target)
         if hecksagon
-          reached << "this hecksagon uses_framework #{target.inspect}" if hecksagon.framework_members.include?(target)
+          reached << "this hecksagon attaches #{target.inspect}" if hecksagon.attaches?(target)
           if hecksagon.subscriptions.any? { |subscribed| Naming.qualifier(subscribed) == target }
             reached << "this hecksagon subscribes to #{target}"
           end

data/lib/hecks/chapters.rb

@@ -1,11 +1,12 @@
 require_relative "naming"
+require_relative "framework"
 require_relative "runtime/registry"
 require_relative "bluebook/meta_validator"
 
 module Hecks
   # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
-  # declared in itself, Expression, Tenancy, Deploy and QualityControl. Framework members stay in
-  # `Framework`.
+  # declared in itself, Expression, Tenancy, Deploy, Site and QualityControl. Framework members stay
+  # in `Framework`; `table` and `attach!` find a name across both.
   #
   # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
   # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
@@ -14,7 +15,7 @@ module Hecks
   module Chapters
     # Where attachable chapters live, relative to `lib/hecks/`.
     GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
-               deploy/bluebook/*.bluebook quality_control/*.bluebook].freeze
+               deploy/bluebook/*.bluebook site/bluebook/*.bluebook quality_control/*.bluebook].freeze
 
     # Every attachable chapter, by name, with the files that declare it.
     #
@@ -26,6 +27,33 @@ module Hecks
                       .freeze
     end
 
+    # Every chapter the gem carries, whichever module loads it: the one lookup table `attaches`
+    # finds a name in.
+    #
+    # @return [Hash{String => Array<String>}] chapter name to its files' absolute paths, the
+    #   framework members (`Framework.members`) and the attachable chapters (`index`) together
+    def self.table
+      Framework.members.transform_values { |path| [path] }.merge(index)
+    end
+
+    # Loads one gem chapter by name, found in `table`: a framework member through
+    # `Framework.load!`, any other chapter through `load!`.
+    #
+    # @param name [String, Symbol] the chapter's name, such as `"Governance"` or `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded it, nil when it was already held
+    # @raise [Runtime::WiringError] if the gem carries no chapter of that name; the message
+    #   lists the known names and says how to attach a vendored package
+    def self.attach!(name)
+      key = name.to_s
+      return Framework.load!(key) if Framework.members.key?(key)
+      return load!(key) if index.key?(key)
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}: the gem carries no chapter of that name — known: " \
+            "#{table.keys.sort.join(', ')}. To attach a vendored package, write " \
+            "`attaches #{name.to_s.inspect}, from: :vendor`"
+    end
+
     # Loads a chapter's files into the current registry, unless it already holds the chapter.
     #
     # The files load together inside `MetaValidator.defer`, so a chapter spread over several files

data/lib/hecks/cli/check_era.rb

@@ -28,7 +28,7 @@ module Hecks
       # @raise [Errno::ENOENT, Errno::EACCES] if the file cannot be read
       # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
       # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
-      def assess(url, file, timeout: 10)
+      def assess(url, file, timeout:)
         expected = Runtime::EraCheck::ExpectedEra
         allowed  = expected.parse(File.read(file))
         document = expected.fetch_version(url, timeout: timeout)

data/lib/hecks/cli/console.rb

@@ -9,7 +9,7 @@ module Hecks
     # The command behind `hecks console` and Custodian's `Operation.OpenConsole`: boots a domain
     # (pizzas on Memory by default) and drops into IRB with its door installed, for dispatching a
     # real command by hand. No argument needs no database (ADR 0073); a domain directory boots as
-    # it is wired, which may bind PostgresEra.
+    # it is wired, which may bind PostgresEra (examples/directory does).
     module Console
       PIZZAS = File.expand_path("../../../examples/pizzas", __dir__)
 
@@ -25,14 +25,27 @@ module Hecks
       # @param domain [String, nil] a domain directory; the bundled pizzas domain when nil
       # @param launcher [#call] starts the interactive session; IRB unless a caller stands in
       # @return [Runtime] the runtime the session ran against
-      def call(domain = nil, launcher: -> { IRB.start(__FILE__) })
+      def call(domain = nil, launcher: -> { irb_session })
         runtime = domain ? Hecks.boot(domain) : Hecks.boot_files(DEFAULT_FILES)
         puts overview(runtime)
-        puts banner
+        puts banner(domain)
         launcher.call
         runtime
       end
 
+      # Starts IRB with an empty command line. IRB reads `ARGV` for a script to run, and a
+      # launcher's `ARGV` holds its own words (`console`, `subject=<domain>`), which IRB would
+      # open as a file and then exit without a prompt.
+      #
+      # @return [void] when the session ends; `ARGV` is restored
+      def irb_session
+        words = ARGV.dup
+        ARGV.clear
+        IRB.start(__FILE__)
+      ensure
+        ARGV.replace(words)
+      end
+
       # @param runtime [Runtime] a booted domain
       # @return [String] each chapter's vision and its aggregates' commands
       def overview(runtime)
@@ -46,16 +59,19 @@ module Hecks
         end.join
       end
 
-      # @return [String] the version and a first session to try against the pizzas domain
-      def banner
+      # @param domain [String, nil] a domain directory, or nil for the bundled pizzas domain
+      # @return [String] the version, and for the pizzas domain a first session to try
+      def banner(domain = nil)
+        return "\nhecks #{Hecks::VERSION}\n\n" if domain
+
         <<~BANNER
 
           hecks #{Hecks::VERSION}
 
           try:
-            order = Order.create_pizza!(name: { value: "Margherita" }, pizza: { price_cents: { cents: 1200 }, size: { value: "large" } })
-            order.add_topping!(topping: { value: "Basil" }, amount: { value: 3 })
-            order.purchase!(customer_name: { value: "Chris" }, amount: { cents: 1200 })
+            order = Order.create_pizza!(name: "Margherita", pizza: { price_cents: { cents: 1200 }, size: "large" })
+            order.add_topping!(topping: "Basil", amount: 3)
+            order.purchase!(customer_name: "Chris", amount: { cents: 1200 })
             order.status
             order.events.last
 

data/lib/hecks/cli/deploy_template_diff.rb

@@ -5,7 +5,7 @@ require_relative "../projections/deploy/template_diff"
 
 module Hecks
   module CLI
-    # The command behind `hecks deploy diff` and `hecks deploy diff`: compares two
+    # The command behind `hecks deploy template_comparison.diff`: compares two
     # CloudFormation templates offline and reports differences by logical id; `--strict` also
     # counts cosmetic differences (comments, key order).
     module DeployTemplateDiff

data/lib/hecks/cli/doc_coverage.rb

@@ -24,7 +24,7 @@ module Hecks
         return 0 if clean
 
         err.puts "docs/implemented/reference/ is behind the language. " \
-                 "Regenerate with hecks project_reference to see the words in place."
+                 "Regenerate with hecks language_run.project_reference to see the words in place."
         1
       end
     end