hecks 4.0.0 → 6.0.0

data/lib/hecks/cli/interview_shape.rb

@@ -1,4 +1,6 @@
 require_relative "../naming"
+require_relative "../text"
+require_relative "interview_shape/lifecycle"
 
 module Hecks
   module CLI
@@ -9,6 +11,13 @@ module Hecks
     # Pure, like `InterviewDraft`, which calls it: each method answers lines of bluebook text and
     # writes none. A name is written as `InterviewDraft.word` writes it.
     module InterviewShape
+      # An ` or ` between the alternatives an expert names.
+      ALTERNATIVE = /\s+or\s+/
+      # A comma or an ` or `: what separates the values an expert lists.
+      VALUE_SEPARATOR = /\s*,\s*|\s+or\s+/
+
+      extend Lifecycle
+
       module_function
 
       # The accepted fields of one thing, each with the type it will be written under. The
@@ -55,7 +64,8 @@ module Hecks
       # @param action [Hash] an accepted action
       # @return [Array<String>] snake-cased field names
       def takes(action)
-        action[:takes].to_s.split(/\s*,\s*/).map { |text| Naming.snake(InterviewDraft.word(text)) }.reject(&:empty?)
+        names = action[:takes].to_s.split(Text::COMMA).map { |text| Naming.snake(InterviewDraft.word(text)) }
+        names.reject(&:empty?)
       end
 
       # What an action is told that the thing has as a field, and what it names that the thing
@@ -99,35 +109,6 @@ module Hecks
         by.empty? ? [] : ["      # Who: #{by}. Declare it as a role once Governance is attached."]
       end
 
-      # The lifecycle the accepted transitions describe. The state a creating action's step
-      # leads to is where a thing starts; a step for an action the thing does not have is kept
-      # as a comment.
-      #
-      # @param steps [Array<Hash>] the thing's accepted transitions
-      # @param creating [Array<Hash>] the accepted actions that create it
-      # @param rest [Array<Hash>] its other accepted actions
-      # @return [Array<String>] the lines, or none when no step and start state can be placed
-      def lifecycle(steps, creating, rest)
-        starts, moves = steps.partition { |step| names_action?(creating, step) }
-        placed, loose = moves.partition { |step| names_action?(rest, step) }
-        placed = merged(placed)
-        start = beginning(starts, placed)
-        return [] if start.empty? || placed.empty?
-
-        lifecycle_block(start, placed, loose)
-      end
-
-      # @api private
-      def lifecycle_block(start, placed, loose)
-        ["", "    lifecycle :status, default: #{start.inspect} do", *placed.map { |step| transition_line(step) },
-         "    end", *loose.map { |step| loose_line(step) }]
-      end
-
-      # @api private
-      def names_action?(actions, step)
-        actions.map { |action| InterviewDraft.word(action[:name]) }.include?(InterviewDraft.word(step[:action]))
-      end
-
       # One action for each name: an expert who refines an answer gets the same action accepted more
       # than once, and a command can be declared only once. The first one's event and place in the
       # interview stay; what each takes is joined, who does it is joined, and it creates if any did.
@@ -143,8 +124,10 @@ module Hecks
 
       # @api private
       def joined(group, key, separator)
-        parts = group.flat_map { |a| a[key].to_s.split(separator == ", " ? /\s*,\s*/ : /\s+or\s+/) }
-        parts.map(&:strip).reject(&:empty?).uniq.join(separator)
+        pattern = separator == ", " ? Text::COMMA : ALTERNATIVE
+        parts = group.flat_map { |a| a[key].to_s.split(pattern) }
+        kept = parts.map(&:strip).reject(&:empty?)
+        kept.uniq.join(separator)
       end
 
       # @api private
@@ -155,51 +138,14 @@ module Hecks
         type = Naming.pascal(field)
         type = "#{type}Value" while taken.include?(type)
         taken << type
-        { name: field, type: type, values: finding[:values].to_s.split(/\s*,\s*|\s+or\s+/).map(&:strip).reject(&:empty?).uniq }
+        { name: field, type: type, values: listed_values(finding[:values]) }
       end
 
-      # One step for each action and state it leads to: the states it starts from are joined, and a
-      # step with no state to start from means it may be taken from any.
       # @api private
-      def merged(steps)
-        steps.group_by { |step| [InterviewDraft.word(step[:action]), state_word(step[:to])] }.values.map do |group|
-          froms = group.map { |step| step[:from].to_s.strip }
-          group.first.merge(from: froms.any?(&:empty?) ? "" : froms.join(","))
-        end
+      def listed_values(text)
+        parts = text.to_s.split(VALUE_SEPARATOR).map(&:strip)
+        parts.reject(&:empty?).uniq
       end
-
-      # The state a thing starts in: where its creating action's step leads, else the first state a
-      # change is said to start from.
-      # @api private
-      def beginning(starts, placed)
-        from = placed.map { |step| step[:from].to_s.split(",").first }.find { |text| !text.to_s.strip.empty? }
-        state_word(starts.first&.fetch(:to) || from)
-      end
-
-      # @api private
-      def transition_line(step)
-        "      transition #{InterviewDraft.word(step[:action]).inspect} => #{state_word(step[:to]).inspect}" \
-          "#{from_clause(step)}"
-      end
-
-      # @api private
-      def loose_line(step)
-        "    # UNPLACED transition: #{InterviewDraft.word(step[:action])} to #{state_word(step[:to])}; " \
-          "no accepted action has that name."
-      end
-
-      # The states a step may start from: none, one, or several.
-      # @api private
-      def from_clause(step)
-        states = step[:from].to_s.split(/\s*,\s*/).map { |text| state_word(text) }.reject(&:empty?)
-        return "" if states.empty?
-
-        states.one? ? ", from: #{states.first.inspect}" : ", from: %w[#{states.join(" ")}]"
-      end
-
-      # A state as a lowercase word: `Not Yet Triaged` is `not_yet_triaged`.
-      # @api private
-      def state_word(text) = text.to_s.strip.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_|_\z/, "")
     end
   end
 end

data/lib/hecks/cli/model_check/examination.rb

@@ -1,36 +1,85 @@
+require_relative "../../projections/context_relationships"
+
 module Hecks
   module CLI
     module ModelCheck
       # Examining booted domains: each one's findings against the allowlist, then the language's
-      # own chapters, printed as the check goes. `ModelCheck` extends it.
+      # own bluebooks, printed as the check goes. `ModelCheck` extends it.
       module Examination
         # @api private
         def examine_all(booted, options)
           known_domains = booted.flat_map { |_, registry| registry.bluebooks.keys + registry.hecksagons.keys }.to_set
-          shared = { known_domains: known_domains, global_emitted_events: emitted_events_of(booted) }
+          owners = aggregate_owners_of(booted)
+          shared = { known_domains: known_domains, global_emitted_events: emitted_events_of(booted),
+                     aggregate_owners: owners }
+
+          domains_ok = booted.reduce(true) do |all_ok, (name, registry)|
+            domain_passes?(name, registry, options, shared) && all_ok
+          end
+          contexts_pass?(booted, owners) && domains_ok
+        end
+
+        # Each aggregate name to the contexts that declare it, across every booted registry.
+        #
+        # @api private
+        def aggregate_owners_of(booted)
+          pairs = booted.flat_map do |_, registry|
+            registry.bluebooks.values.flat_map do |declaration|
+              declaration.aggregates.map { |aggregate| [aggregate.hecks_name, declaration.name.to_s] }
+            end
+          end
+          pairs.group_by(&:first).transform_values { |rows| rows.map(&:last).uniq }
+        end
 
-          booted.reduce(true) { |all_ok, (name, registry)| domain_passes?(name, registry, options, **shared) && all_ok }
+        # The checks that need every context at once: cycles between contexts, and each declared
+        # context map held to the wiring of the system it covers. Prints a section only when it
+        # finds something.
+        #
+        # @api private
+        def contexts_pass?(booted, owners)
+          edges = booted.flat_map do |_, registry|
+            Projections::ContextRelationships.call(registry: registry, owners: owners)
+          end
+          findings = Bluebook::ModelCheck.context_cycle_findings(edges.uniq) + context_map_findings(booted, owners)
+          return true if findings.empty?
+
+          puts "── contexts"
+          passes?(findings, "")
+        end
+
+        # What each booted system's declared context maps say about that system's own wiring.
+        #
+        # @api private
+        # @return [Array<Bluebook::ModelCheck::Finding>] the findings of every map, none for a
+        #   system that declares no map
+        def context_map_findings(booted, owners)
+          booted.flat_map do |_, registry|
+            registry.context_maps.flat_map do |map|
+              edges = Projections::ContextRelationships.call(registry: registry, owners: owners)
+              Bluebook::ModelCheck.context_map_findings(map, edges)
+            end
+          end
         end
 
         # @api private
         def emitted_events_of(booted)
           booted.flat_map do |_, registry|
-            registry.bluebooks.values.flat_map { |chapter| Bluebook::ModelCheck.emitted_events(chapter) }
+            registry.bluebooks.values.flat_map { |declaration| Bluebook::ModelCheck.emitted_events(declaration) }
           end.to_set
         end
 
-        def domain_passes?(name, registry, options, known_domains:, global_emitted_events:)
+        def domain_passes?(name, registry, options, shared)
           puts "── #{name}"
 
-          scope = { known_domains: known_domains, global_emitted_events: global_emitted_events,
-                    rust_target: rust_target?(name, options.rust_dir), strict: options.strict, profile: options.profile }
-          chapters = registry.bluebooks.values
-          findings = chapters.flat_map do |chapter|
-            Bluebook::ModelCheck.call(chapter, hecksagon: registry.hecksagon(chapter.name), **scope)
+          scope = shared.merge(rust_target: rust_target?(name, options.rust_dir), strict: options.strict,
+                               profile: options.profile)
+          declarations = registry.bluebooks.values
+          findings = declarations.flat_map do |declaration|
+            Bluebook::ModelCheck.call(declaration, hecksagon: registry.hecksagon(declaration.name), **scope)
           end
 
           remaining = without_allowlisted(name, findings) or return false
-          passes?(remaining, "   clean — #{chapters.size} chapter(s), no dead states, no unreachable protocol steps")
+          passes?(remaining, "   clean — #{declarations.size} bluebook(s), no dead states, no unreachable protocol steps")
         end
 
         # Prints the allowlisted findings and answers the rest.
@@ -56,11 +105,11 @@ module Hecks
         def examine_language(options)
           ok = true
           ["Bluebook", "World"].each do |name|
-            chapter = Bluebook::MetaValidator.grammar_registry.bluebook(name)
-            next unless chapter
+            declaration = Bluebook::MetaValidator.grammar_registry.bluebook(name)
+            next unless declaration
 
             puts "── #{name} (the language itself)"
-            findings = Bluebook::ModelCheck.call(chapter, strict: options.strict, profile: options.profile)
+            findings = Bluebook::ModelCheck.call(declaration, strict: options.strict, profile: options.profile)
             ok = passes?(findings, "   clean — no dead states, no unreachable protocol steps") && ok
           end
           ok

data/lib/hecks/cli/model_check/sources.rb

@@ -9,6 +9,8 @@ module Hecks
           "ports/persistence.port", "ports/extraction.port",
           "adapters/driven/memory.adapter", "adapters/driven/prism.adapter"
         ].freeze
+        # The `.bluebook` extension ending a source path.
+        BLUEBOOK_EXTENSION = /\.bluebook\z/
 
         # `root:` is the source's parent, so a member declaring
         # `attaches ... from: :vendor` can vendor from it.
@@ -31,7 +33,7 @@ module Hecks
 
           # A port attaches to its aggregate from the hecksagon, not the bluebook, so a
           # deaf-policy check that skipped it would miss a policy reacting to an event
-          # nothing emits. Recording a bind builds IR only; no adapter resolves here. A chapter
+          # nothing emits. Recording a bind builds IR only; no adapter resolves here. A bluebook
           # that ships its ports beside its bluebook (`<name>.ports.hecksagon`) is read with them.
           hecksagons_of(source).each { |hecksagon| Kernel.load(hecksagon) if File.exist?(hecksagon) }
         end
@@ -40,7 +42,7 @@ module Hecks
         def hecksagons_of(source)
           return Dir.glob(File.join(source, "*.hecksagon")) if File.directory?(source)
 
-          [".hecksagon", ".ports.hecksagon"].map { |suffix| source.sub(/\.bluebook\z/, suffix) }
+          [".hecksagon", ".ports.hecksagon"].map { |suffix| source.sub(BLUEBOOK_EXTENSION, suffix) }
         end
 
         # The same rule `Corpus.bluebook_dir` applies.

data/lib/hecks/cli/model_check.rb

@@ -13,7 +13,7 @@ module Hecks
     # fires, in silence.
     #
     # Given domain paths it checks just those, cross-domain; given none it sweeps
-    # the repository's corpus and the language's own chapters, which needs `root:`.
+    # the repository's corpus and the language's own bluebooks, which needs `root:`.
     module ModelCheck
       # The directory the framework's own `.port` and `.adapter` files live under.
       HECKS_DIR = File.expand_path("..", __dir__)

data/lib/hecks/cli/persistence_notice.rb

@@ -0,0 +1,45 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The notice `hecks stores` and `hecks history` print when nothing is persisted. Hecks is in
+    # Memory unless a local hecksagon opts it in (ADR 0136), so a fresh process holds no records and
+    # no journal, and the plain JSON they print would read as an empty store rather than as a store
+    # that was never kept.
+    module PersistenceNotice
+      module_function
+
+      # Writes the notice to standard error when every aggregate of the booted domain is in Memory.
+      # Standard error keeps standard output the JSON document the command promises.
+      #
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @param program [String] the name the notice calls the command by
+      # @return [void]
+      def announce(registry, program:)
+        warn "#{program}: #{message_for(registry)}" unless persisted?(registry)
+      end
+
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @return [Boolean] whether any aggregate is bound to a store other than Memory
+      def persisted?(registry)
+        adapters(registry).any? { |adapter| adapter != Ports::Persistence::DEFAULT_ADAPTER }
+      end
+
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @return [Array<String>] the adapter each aggregate of each bluebook resolves to
+      def adapters(registry)
+        registry.bluebooks.flat_map do |name, bluebook|
+          bluebook.aggregates.map { |aggregate| Ports::Persistence::BindingPolicy.resolve(registry, name, aggregate).adapter }
+        end
+      end
+
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @return [String] what is true of this run and how to keep records instead
+      def message_for(registry)
+        "nothing is persisted: #{adapters(registry).size} aggregates are in Memory, so this process holds no " \
+          "records and no history. To keep them, add a hecks.local.hecksagon with `persisted_by \"PostgresEra\"` " \
+          "and a hecks.local.world with `default_database` (ADR 0136)."
+      end
+    end
+  end
+end

data/lib/hecks/cli/present.rb

@@ -9,7 +9,7 @@ module Hecks
     # forms and views, backed by the in-memory adapter
     # (docs/command-form-and-query-form-bluebook.md).
     #
-    # Then, for example, `http://localhost:4567/` lists every exposed chapter,
+    # Then, for example, `http://localhost:4567/` lists every exposed bluebook,
     # `/Banking/Customer.html` every Customer plus Register, `/Banking/Account/Overdrawn.html` a
     # query view, and `/Banking/Account/Debit` answers the command's shape as JSON.
     module Present

data/lib/hecks/cli/project_cli/launcher_source.rb

@@ -8,7 +8,7 @@ module Hecks
       module LauncherSource
         include Templates
 
-        # What a chapter name, a domain path and a launcher command may be made of.
+        # What a bluebook name, a domain path and a launcher command may be made of.
         NAME = /\A[A-Za-z][A-Za-z0-9_ ]*\z/
         PATH = %r{\A[\w./-]+\z}
         VERB = /\A[A-Za-z_][A-Za-z0-9_]*\z/
@@ -36,7 +36,7 @@ module Hecks
           if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))
             why = begin
               require "json"
-              JSON.parse(text).dig("state", "refusal", "value")
+              JSON.parse(text).dig("state", "refusal")
             rescue JSON::ParserError
               nil
             end
@@ -61,32 +61,34 @@ module Hecks
         # An `opted` one also sets UTF-8 and prints a failed `--wait` record on stdout. An
         # executable's program name is its file's basename, and its header names the generator.
         # @param path [String] the domain's directory under the root
-        # @param name [String] the chapter's name
+        # @param name [String] the bluebook's name
         # @param program [String] the generator's invocation, named in the header
         # @param executable [String, nil] the file's path under the root when not beside the domain
         # @param legacy [Array<String>, nil] commands an executable hands to `Hecks::CLI` first
         # @param memory_commands [Array<String>, nil] commands that default to Memory
-        # @param opted [Boolean] whether the chapter's world declares a `launcher` setting
+        # @param opted [Boolean] whether the bluebook's world declares a `launcher` setting
         # @return [String] the Ruby source
         # @raise [ArgumentError] if a name, path, executable or legacy command is not plain
         def launcher(path, name, program, executable: nil, legacy: nil, memory_commands: nil, opted: !executable.nil?) # rubocop:disable Metrics/ParameterLists -- the generator's documented signature
-          plain!("chapter name", name, NAME)
+          plain!("bluebook name", name, NAME)
           plain!("domain path", path, PATH)
           site = executable ? executable_site(path, executable) : plain_site(path, name, program)
           quiet = !Array(memory_commands).empty?
 
           render(LAUNCHER, name: name, program: site.program, where: site.where, up: site.up,
-                           encoding: opted ? ENCODING : "", handoff: handoff_for(executable, legacy, memory_commands),
+                           encoding: opted ? ENCODING : "",
+                           handoff: handoff_for(executable, legacy, memory_commands, site),
                            ending: ending_for(opted, executable && quiet),
                            entry: entry(name, site.boot, site.shown, opted, quiet: quiet))
         end
 
         # @api private
-        # @return [String] what an executable launcher does before it boots, or nothing
-        def handoff_for(executable, legacy, memory_commands)
+        # @return [String] what an executable launcher does before it boots, or nothing: it takes
+        #   the gems the checkout's Gemfile pins, hands legacy commands on, defaults Memory ones
+        def handoff_for(executable, legacy, memory_commands, site)
           return "" unless executable
 
-          legacy_handoff(Array(legacy)) + memory_default(Array(memory_commands))
+          render(PINNED_GEMS, up: site.up) + legacy_handoff(Array(legacy)) + memory_default(Array(memory_commands))
         end
 
         # @api private
@@ -109,7 +111,7 @@ module Hecks
         end
 
         # @api private
-        # @return [Site] where a launcher sits beside its domain, named after its chapter
+        # @return [Site] where a launcher sits beside its domain, named after its bluebook
         def plain_site(path, name, program)
           where = "#{path}/#{Naming.snake(name)}"
           Site.new("../" * path.count("/").succ, "__dir__", program, where, where)

data/lib/hecks/cli/project_cli/templates.rb

@@ -3,6 +3,9 @@ module Hecks
     module ProjectCli
       # The text of a launcher, as templates: each `{{name}}` is filled in by `render`.
       module Templates
+        # A `{{name}}` placeholder; the name is its first group.
+        PLACEHOLDER = /\{\{(\w+)\}\}/
+
         # The whole launcher: its header, the load path, the hand-offs, the entry and the ending.
         LAUNCHER = <<~RUBY.freeze
           #!/usr/bin/env ruby
@@ -11,7 +14,7 @@ module Hecks
           #
           # 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.
+          # to the bluebook shows up here without re-minting anything.
           #
           #   {{where}}                  every command, and every question
           #   {{where}} <command> --help    what it wants, and how it refuses
@@ -27,7 +30,7 @@ module Hecks
         # An opted-in launcher's middle: usage answered from the projection, a boot only for a
         # line that runs a command.
         DESCRIBED_ENTRY = <<~'RUBY'.freeze
-          # Usage is answered from the projected chapter alone: no adapter is bound and no
+          # Usage is answered from the projected bluebook alone: no adapter is bound and no
           # database is opened. Only a line that runs a command boots the domain,
           # and it boots from what the usage check already loaded.
           domain = {{boot}}
@@ -80,6 +83,24 @@ module Hecks
           ARGV << "--wait" if MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!")) && !ARGV.include?("--wait")
         RUBY
 
+        # The lines that put a checkout's launcher on the gems its Gemfile pins. They do nothing
+        # beside an installed gem, where no Gemfile stands next to the gemspec, and they leave the
+        # gems at hand when the pinned set is not installed.
+        PINNED_GEMS = <<~RUBY.freeze
+
+          # In a hecks checkout this runs on the gems the Gemfile pins, as `bundle exec` and CI do.
+          # Beside an installed gem, or where that set is not installed, it runs on the gems at hand.
+          gemfile = File.expand_path("{{up}}Gemfile", __dir__)
+          if File.exist?(File.expand_path("{{up}}hecks.gemspec", __dir__)) && File.exist?(gemfile)
+            ENV["BUNDLE_GEMFILE"] ||= gemfile
+            begin
+              require "bundler/setup"
+            rescue LoadError, StandardError
+              nil
+            end
+          end
+        RUBY
+
         # The lines that hand the legacy commands to `Hecks::CLI`.
         LEGACY_HANDOFF = <<~RUBY.freeze
 
@@ -98,7 +119,7 @@ module Hecks
         # @return [String] the text with every placeholder replaced
         # @raise [KeyError] if the template names a placeholder `values` lacks
         def render(template, values)
-          template.gsub(/\{\{(\w+)\}\}/) { values.fetch(Regexp.last_match(1).to_sym) }
+          template.gsub(PLACEHOLDER) { values.fetch(Regexp.last_match(1).to_sym) }
         end
       end
     end

data/lib/hecks/cli/project_cli.rb

@@ -10,10 +10,10 @@ module Hecks
     #
     # Each launcher is a dozen lines pinning one directory and handing over to
     # `Adapters::Driving::CliRunner`; the surface itself is projected at the moment it runs,
-    # so editing a chapter changes behaviour without regenerating anything.
+    # so editing a bluebook changes behaviour without regenerating anything.
     #
-    # A chapter whose world's `launcher` setting names an `executable` gets its launcher
-    # there instead: the Hecks chapter's is the gem's `exe/hecks`.
+    # A bluebook whose world's `launcher` setting names an `executable` gets its launcher
+    # there instead: the Hecks bluebook's is the gem's `exe/hecks`.
     module ProjectCli
       # Raised when the project loads no bluebook.
       class Error < RuntimeError; end
@@ -21,8 +21,8 @@ module Hecks
       # Build output and other trees under a root that hold no domain a caller means.
       IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
 
-      # One launcher to write: its chapter's name, its label under the root, its file, its text,
-      # the snake-cased name and the executable path its chapter's world named (nil when none).
+      # One launcher to write: its bluebook's name, its label under the root, its file, its text,
+      # the snake-cased name and the executable path its bluebook's world named (nil when none).
       Target = Struct.new(:name, :label, :file, :text, :snake, :executable)
 
       extend LauncherSource
@@ -92,11 +92,11 @@ module Hecks
       #   launcher could not be made
       def one(root, path, program, check, remove_stale_bin)
         runtime = Hecks.boot(File.join(root, path), install_driving: false)
-        name    = runtime.registry.bluebooks.keys.first or raise Error, "it loads no bluebook"
+        name    = runtime.bluebooks.keys.first or raise Error, "it loads no bluebook"
         setting = Adapters::Driving::LauncherOptions.settings(runtime, name) || {}
         settle(launcher_target(name, path, setting, root, program), path, root, check, remove_stale_bin)
       rescue StandardError, LoadError => e
-        refuse(path, "cannot boot — #{e.message.lines.first.to_s.strip}")
+        refuse(path, "cannot boot — #{Text.first_line(e.message)}")
       end
 
       # Checks the launcher against its file, or writes it.
@@ -149,12 +149,10 @@ module Hecks
 
       def domains(root)
         folder = Adapters::Folder.new
-        Dir.glob(File.join(root, "**/*.hecksagon"))
-           .map { |path| folder.domain_root(File.dirname(path)) }
-           .compact
-           .map { |path| path.delete_prefix("#{root}/") }
-           .grep_v(IGNORED)
-           .uniq.sort
+        wiring = Dir.glob(File.join(root, "**/*.hecksagon"))
+        roots = wiring.map { |path| folder.domain_root(File.dirname(path)) }
+        relative = roots.compact.map { |path| path.delete_prefix("#{root}/") }
+        relative.grep_v(IGNORED).uniq.sort
       end
     end
   end

data/lib/hecks/cli/project_diagrams.rb

@@ -3,52 +3,52 @@ require_relative "../../hecks"
 module Hecks
   module CLI
     # The command behind `hecks project_diagrams`: boots a
-    # domain, finds the chapter it names, and writes its Mermaid diagrams
-    # (`Projections::Diagrams`) under `docs/generated/diagrams/<chapter>/` below the
-    # root. Only this positional form writes; the launcher's `domain=… chapter=…` question
+    # domain, finds the bluebook it names, and writes its Mermaid diagrams
+    # (`Projections::Diagrams`) under `docs/generated/diagrams/<bluebook>/` below the
+    # root. Only this positional form writes; the launcher's `domain=… bluebook=…` question
     # prints the same files' text and writes nothing.
     module ProjectDiagrams
       module_function
 
-      # Writes the chapter's diagrams and prints each file written.
+      # Writes the bluebook's diagrams and prints each file written.
       #
-      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param argv [Array<String>] the domain path, then the bluebook's name
       # @param program [String] the name the usage line shows
       # @param root [String] the directory `docs/generated/diagrams/` lives under
       # @return [void]
       # @raise [SystemExit] with the usage line when an argument is missing, or when the
-      #   domain has no chapter of that name
+      #   domain has no bluebook of that name
       def call(argv, program:, root:)
-        usage = "usage: #{program} <domain-path> <ChapterName>"
-        domain_path  = argv[0] or abort usage
-        chapter_name = argv[1] or abort usage
+        usage = "usage: #{program} <domain-path> <BluebookName>"
+        domain_path = argv[0] or abort usage
+        declaration_name = argv[1] or abort usage
 
-        chapter, hecksagon = boot_chapter(domain_path, chapter_name)
-        directory = File.expand_path("docs/generated/diagrams/#{Naming.snake(chapter_name)}", root)
+        declaration, hecksagon = boot_bluebook(domain_path, declaration_name)
+        directory = File.expand_path("docs/generated/diagrams/#{Naming.snake(declaration_name)}", root)
 
-        report(chapter_name, directory, write_diagrams(chapter, hecksagon, directory))
+        report(declaration_name, directory, write_diagrams(declaration, hecksagon, directory))
       end
 
       # @api private
-      # @return [Array(Object, Object)] the named chapter and its hecksagon
-      def boot_chapter(domain_path, chapter_name)
+      # @return [Array(Object, Object)] the named bluebook and its hecksagon
+      def boot_bluebook(domain_path, declaration_name)
         registry = Hecks.boot(File.expand_path(domain_path, Dir.pwd)).registry
-        chapter = registry.bluebook(chapter_name) or abort "no chapter named #{chapter_name}"
-        [chapter, registry.hecksagon(chapter_name)]
+        declaration = registry.bluebook(declaration_name) or abort "no bluebook named #{declaration_name}"
+        [declaration, registry.hecksagon(declaration_name)]
       end
 
       # @api private
-      def write_diagrams(chapter, hecksagon, directory)
+      def write_diagrams(declaration, hecksagon, directory)
         Projector.write(
-          Projector.call(:diagrams, bluebook: chapter, options: { hecksagon: hecksagon }),
+          Projector.call(:diagrams, bluebook: declaration, options: { hecksagon: hecksagon }),
           directory, as: :files
         )
       end
 
       # @api private
-      def report(chapter_name, directory, written)
+      def report(declaration_name, directory, written)
         if written.empty?
-          puts "#{chapter_name} declares no lifecycle, relationship, or dispatch to project yet"
+          puts "#{declaration_name} declares no lifecycle, relationship, or dispatch to project yet"
         else
           puts "wrote #{written.size} diagram(s) to #{directory}:"
           written.each { |path| puts "  #{path}" }