hecks 5.0.0 → 7.0.0

data/lib/hecks/projector/cli_projector.rb

@@ -3,9 +3,15 @@ require_relative "cli_projector/claims"
 require_relative "cli_projector/command_specs"
 require_relative "cli_projector/query_specs"
 require_relative "cli_projector/option_specs"
+require_relative "cli_projector/renames"
 require_relative "cli_projector/usage"
 require_relative "cli_projector/listing"
+require_relative "cli_projector/everyday"
 require_relative "cli_projector/command_help"
+require_relative "cli_projector/modules"
+require_relative "cli_projector/search"
+require_relative "cli_projector/completion"
+require_relative "cli_projector/json_listing"
 
 module Hecks
   module Projector
@@ -17,10 +23,21 @@ module Hecks
     module CliProjector
       module_function
 
+      # The alias tables: each command and query under its short name and its old spellings, and
+      # the renamed table's old names routed to the namespace of their targets.
+      #
+      # @return [Hash{Symbol => Object}] `:command` and `:question` alias tables, and `:renamed`
+      #   (the old spellings and their argument renames)
+      def launcher_names(commands, questions, renamed)
+        table = renamed_aliases(commands, questions, renamed)
+        { command: aliases(commands).merge(table[:command]), question: aliases(questions).merge(table[:question]),
+          renamed: { spellings: Hash(renamed).keys.map(&:to_s), arguments: renamed_arguments(renamed) } }
+      end
+
       # Projects the command and question tables and the usage text. Commands and queries are
-      # separate namespaces (a chapter may declare both under one name); ask a query with `ask`.
+      # separate namespaces (a bluebook may declare both under one name); ask a query with `ask`.
       #
-      # @param bluebook [Bluebook::Chapter] the booted domain to project
+      # @param bluebook [Bluebook::Declaration] the booted domain to project
       # @param options [Hash{Symbol => Object}] `:program` (default `"hecks run"`) for the usage
       #   text; `:command` and `:ask` select one command's `--help` text; `:names` maps a launcher
       #   name to the command it stands for (`{ "mcp" => "serve_mcp" }`); `:mint_run_keys` makes a
@@ -41,17 +58,23 @@ module Hecks
         display_names([commands, questions], options[:names])
 
         { commands: commands, questions: questions,
-          names: { command: aliases(commands), question: aliases(questions) },
+          names: launcher_names(commands, questions, options[:renamed]),
           usage: usage(bluebook, commands, questions, options) }
       end
 
       extend Claims
+      extend Renames
       extend CommandSpecs
       extend QuerySpecs
       extend OptionSpecs
       extend Usage
       extend Listing
+      extend Everyday
       extend CommandHelp
+      extend Modules
+      extend Search
+      extend Completion
+      extend JsonListing
     end
   end
 end

data/lib/hecks/projector/docs_projector/behaviour.rb

@@ -67,7 +67,7 @@ module Hecks
 
         def command_argument_rows(arguments, holder)
           arguments.map do |attribute|
-            shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : Attributes.shape_of(attribute, holder)
+            shape = attribute.reference? ? "id of a `#{attribute.target_name}`" : Attributes.shape_of(attribute, holder)
             ["`#{attribute.name}`", shape, attribute.optional? ? "" : "required"]
           end
         end
@@ -82,9 +82,10 @@ module Hecks
         def lifecycle_refusals(command, 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
           return [] if froms.empty?
 
           ["`#{lifecycle.field}` is anything other than #{froms.map { |f| "`#{f}`" }.join(" or ")}"]
@@ -93,7 +94,7 @@ module Hecks
         # The refusal for each referenced record that may not exist.
         def reference_refusals(command)
           command.attributes.select(&:reference?).map do |reference|
-            "no `#{reference.type.target_name}` exists for the id given as `#{reference.name}`"
+            "no `#{reference.target_name}` exists for the id given as `#{reference.name}`"
           end
         end
 

data/lib/hecks/projector/docs_projector/closing.rb

@@ -1,19 +1,19 @@
 module Hecks
   module Projector
     module DocsProjector
-      # The sections that close a chapter's document: the reactions its policies cause and the
+      # The sections that close a bluebook's document: the reactions its policies cause and the
       # sagas it runs.
       module Closing
         module_function
 
-        # The closing sections, or `nil` when the chapter has neither policies nor sagas.
+        # The closing sections, or `nil` when the bluebook has neither policies nor sagas.
         def call(bluebook, depth)
           out = reaction_lines(bluebook, depth)
           bluebook.process_managers.each { |saga| out.concat(saga_lines(saga, depth)) }
           out.empty? ? nil : out.join("\n")
         end
 
-        # The table of policies, or no lines when the chapter has none.
+        # The table of policies, or no lines when the bluebook has none.
         def reaction_lines(bluebook, depth)
           return [] if bluebook.policies.empty?
 

data/lib/hecks/projector/docs_projector.rb

@@ -9,11 +9,11 @@ module Hecks
 
       # Projects `bluebook` as Markdown usage documentation.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to document
+      # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook to document
       # @param options [Hash] optional inputs
       # @option options [Integer, String] :heading the top heading level; defaults to 1
       # @option options [String, Symbol, nil] :aggregate narrows the document to one
-      #   aggregate, omitting the chapter header and closing sections
+      #   aggregate, omitting the bluebook header and closing sections
       # @return [String] the document, ending in a newline
       # @raise [Runtime::NotFound] if `options[:aggregate]` names no declared aggregate
       def call(bluebook:, options: {})
@@ -21,7 +21,7 @@ module Hecks
         only  = options[:aggregate]
 
         out = []
-        out << chapter_header(bluebook, depth) unless only
+        out << bluebook_header(bluebook, depth) unless only
         out.concat(aggregate_sections(bluebook, only, depth))
         out << Closing.call(bluebook, depth + 1) unless only
         "#{out.compact.join("\n").rstrip}\n"
@@ -39,12 +39,17 @@ module Hecks
         bluebook.aggregates.find { |aggregate| aggregate.hecks_name == only.to_s } ||
           raise(Runtime::NotFound,
                 "#{bluebook.name} declares no aggregate named #{only.to_s.inspect} — " \
-                "it declares #{bluebook.aggregates.map(&:hecks_name).sort.join(", ")}")
+                "it declares #{declared_aggregates(bluebook)}")
+      end
+
+      def declared_aggregates(bluebook)
+        names = bluebook.aggregates.map(&:hecks_name)
+        names.sort.join(", ")
       end
 
       def h(depth, text) = "#{"#" * depth} #{text}"
 
-      def chapter_header(bluebook, depth)
+      def bluebook_header(bluebook, depth)
         out = [h(depth, bluebook.name), ""]
         out += ["> #{bluebook.vision}", ""] if bluebook.vision
         out.concat(classification_lines(bluebook))
@@ -54,7 +59,7 @@ module Hecks
         out.join("\n")
       end
 
-      # What kind of domain the chapter is and the name it is also known by, when declared.
+      # What kind of domain the bluebook is and the name it is also known by, when declared.
       def classification_lines(bluebook)
         out = []
         out << "#{bluebook.classification.to_s.capitalize} domain." if bluebook.classification
@@ -91,7 +96,7 @@ module Hecks
         out = []
         out << "Identified by `#{aggregate.identity_heads.join("`, `")}`." unless aggregate.identity_heads.empty?
         refs = aggregate.attributes.select(&:reference?)
-        out << "References #{refs.map { |r| "`#{r.type.target_name}`" }.join(", ")}." unless refs.empty?
+        out << "References #{refs.map { |r| "`#{r.target_name}`" }.join(", ")}." unless refs.empty?
         out
       end
 

data/lib/hecks/projector/exporter/adapters.rb

@@ -16,7 +16,8 @@ module Hecks
         end
 
         # Exports one adapter with string keys in the fixed order name, port, fields, secrets,
-        # defaults.
+        # defaults; an adapter that provides capabilities adds `provides`, and a plugin adds
+        # `answers` and `runs` after it.
         #
         # @param adapter [Bluebook::Hecksagon::Adapter] the adapter to export
         # @return [Hash{String => Object}] `"name"` (String), `"port"` (String, nil when never
@@ -29,7 +30,19 @@ module Hecks
             "fields"   => (adapter.fields || []).map(&:to_s),
             "secrets"  => (adapter.secrets || []).map(&:to_s),
             "defaults" => adapter.declared_defaults.to_h { |field, value| [field.to_s, value] }
-          }
+          }.merge(optional_adapter_keys(adapter))
+        end
+
+        # The keys only some adapters carry: `provides` when it names a capability, and a
+        # plugin's `answers` and `runs`.
+        #
+        # @param adapter [Bluebook::Hecksagon::Adapter] the adapter to export
+        # @return [Hash{String => Object}] the keys it carries beyond the five every adapter has
+        def optional_adapter_keys(adapter)
+          keys = adapter.capabilities.empty? ? {} : { "provides" => adapter.capabilities }
+          return keys unless adapter.plugin?
+
+          keys.merge("answers" => adapter.answered_queries, "runs" => adapter.runs)
         end
 
         # Loads each `.adapter` file into its own fresh registry and exports what it declared,

data/lib/hecks/projector/exporter/bindings.rb

@@ -1,38 +1,30 @@
-require_relative "capability_values"
-
 module Hecks
   module Projector
     module Exporter
-      # Which chapter of a registry answers each capability a domain attaches (authorization,
-      # membership, identity, newsletter, registrations, payments): a per-deployment binding fact,
-      # not part of the declared IR. Each answers `{}` when nothing the domain attaches provides it.
+      # Which bluebook of a registry answers each capability a domain attaches (authorization,
+      # membership, identity, and every capability a package declares): a per-deployment binding
+      # fact, not part of the declared IR. Each answers `{}` when nothing the domain attaches
+      # provides it.
       module Bindings
-        include CapabilityValues
-
-        # Which chapter this domain's role checks resolve against
+        # Which bluebook this domain's role checks resolve against
         # (`Registry#authorization_provider_for`); `{}` if none does.
         #
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
         # @param domain_name [String] the domain to export the authorization binding for
-        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:grant`, `:assignments`
-        #   (both provided-verb names), and `:assignment_aggregate` (`:assignments`' own
-        #   leading aggregate name); `{}` if nothing this domain attaches provides
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:grant`, `:assignments` and
+        #   `:live_assignments` (provided-verb names), and `:assignment_aggregate`
+        #   (`:assignments`' own leading aggregate name); `{}` if nothing this domain attaches
+        #   provides
         #   authorization
         def authorization(registry, domain_name)
           provider = registry.authorization_provider_for(domain_name)
           return {} unless provider
 
-          capability = Bluebook::Capabilities::AUTHORIZATION
-          assignments = provider.provided_verb(capability, :assignments)
-          {
-            provider:             provider.name,
-            grant:                provider.provided_verb(capability, :grant),
-            assignments:          assignments,
-            assignment_aggregate: aggregate_of(assignments)
-          }
+          verbs = verbs_of(provider, Bluebook::Capabilities::AUTHORIZATION, :grant, :assignments, :live_assignments)
+          { provider: provider.name, **verbs, assignment_aggregate: aggregate_of(verbs[:assignments]) }
         end
 
-        # Which chapter answers "who may sign in" (`Registry#membership_provider_for`),
+        # Which bluebook answers "who may sign in" (`Registry#membership_provider_for`),
         # with the membership aggregate named off `admit`; `{}` if none does.
         #
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
@@ -48,7 +40,7 @@ module Hecks
           { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:admit]) }
         end
 
-        # Which chapter answers "who is this authenticated pair"; `{}` if none does.
+        # Which bluebook answers "who is this authenticated pair"; `{}` if none does.
         # Breaking in 2.0: Link's reference field is `identity`, never `identity_id`.
         #
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
@@ -68,118 +60,24 @@ module Hecks
           }
         end
 
-        # Which chapter answers the guest newsletter signup
-        # (`Registry#newsletter_provider_for`); `{}` if none does.
-        #
-        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-        # @param domain_name [String] the domain to export the newsletter binding for
-        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:subscribe`, `:add_name`,
-        #   `:confirm`, `:unsubscribe` (qualified verbs), `:aggregate` (`:subscribe`'s own
-        #   leading qualified aggregate name) and, when declared, `:awaiting_confirmation`,
-        #   `:receives_issues` and `:left` (the states of the lifecycle marks they name) and
-        #   `:confirm_window` and `:unsubscribe_window` (seconds); `{}` if nothing this domain
-        #   attaches provides newsletter
-        def newsletter(registry, domain_name)
-          provider = registry.newsletter_provider_for(domain_name)
-          return {} unless provider
-
-          verbs = verbs_of(provider, Bluebook::Capabilities::NEWSLETTER,
-                           :subscribe, :add_name, :confirm, :unsubscribe)
-          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:subscribe]),
-            **all_marked_states(provider, Bluebook::Capabilities::NEWSLETTER),
-            **all_durations(provider, Bluebook::Capabilities::NEWSLETTER) }
-        end
-
-        # Which chapter answers sending a newsletter issue
-        # (`Registry#newsletter_issues_provider_for`); `{}` if none does.
-        #
-        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-        # @param domain_name [String] the domain to export the issue-sending binding for
-        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:send_issue`,
-        #   `:record_delivery` (qualified verbs), `:issue_aggregate` and `:delivery_aggregate`
-        #   (each verb's own leading qualified aggregate name); `{}` if nothing this domain
-        #   attaches provides newsletter_issues
-        def newsletter_issues(registry, domain_name)
-          provider = registry.newsletter_issues_provider_for(domain_name)
-          return {} unless provider
-
-          verbs = verbs_of(provider, Bluebook::Capabilities::NEWSLETTER_ISSUES, :send_issue, :record_delivery)
-          { provider: provider.name, **verbs,
-            **aggregates_of(verbs, issue_aggregate: :send_issue, delivery_aggregate: :record_delivery) }
-        end
-
-        # Which chapter answers scheduling sessions and taking registrations
-        # (`Registry#registrations_provider_for`); `{}` if none does.
-        #
-        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-        # @param domain_name [String] the domain to export the registrations binding for
-        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:schedule`, `:request`
-        #   (qualified verbs), `:event_aggregate` and `:registration_aggregate` (each verb's own
-        #   leading qualified aggregate name) and, when declared, `:frees_seat` (the states of the
-        #   lifecycle mark it names) and `:registered_at` (the attribute that stamps a request);
-        #   `{}` if nothing this domain attaches provides registrations
-        def registrations(registry, domain_name)
-          provider = registry.registrations_provider_for(domain_name)
-          return {} unless provider
-
-          verbs = verbs_of(provider, Bluebook::Capabilities::REGISTRATIONS, :schedule, :request)
-          { provider: provider.name, **verbs,
-            **aggregates_of(verbs, event_aggregate: :schedule, registration_aggregate: :request),
-            **all_marked_states(provider, Bluebook::Capabilities::REGISTRATIONS),
-            **all_words(provider, Bluebook::Capabilities::REGISTRATIONS) }
-        end
-
-        # Which chapter owns the payment-processor connection
-        # (`Registry#payment_connection_provider_for`); `{}` if none does.
+        # Every capability a package declares (one the language defines no contract for), as the
+        # bluebook that provides it for this domain resolves each key: the qualified verb of a
+        # command, query or port operation, the states of a lifecycle mark, or an attribute's
+        # `{ attribute:, default: }`. The reader of a capability checks the keys it needs.
         #
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-        # @param domain_name [String] the domain to export the payment-connection binding for
-        # @return [Hash{Symbol => String, nil}] `:provider` (name), one qualified verb per
-        #   contract key (`:connect`, `:reconnect`, `:disconnect`, `:suspend`, `:resume`,
-        #   `:enable`, `:disable`) and `:aggregate` (`:connect`'s own leading qualified
-        #   aggregate name); `{}` if nothing this domain attaches provides payment_connection
-        def payment_connection(registry, domain_name)
-          provider = registry.payment_connection_provider_for(domain_name)
-          return {} unless provider
-
-          capability = Bluebook::Capabilities::PAYMENT_CONNECTION
-          verbs = verbs_of(provider, capability, *Bluebook::Capabilities::CONTRACTS.fetch(capability).keys)
-          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:connect]) }
-        end
-
-        # Which chapter takes payments (`Registry#payments_provider_for`);
-        # `{}` if none does.
-        #
-        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-        # @param domain_name [String] the domain to export the payments binding for
-        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:initiate`, `:succeeded`,
-        #   `:failed` (qualified verbs), `:aggregate` (`:initiate`'s own leading qualified
-        #   aggregate name) and, when declared, `:holds_seat` (the states of the lifecycle mark
-        #   it names) and `:lapse_reason` (the word a lapsed hold
-        #   records); `{}` if nothing this domain attaches provides payments
-        def payments(registry, domain_name)
-          provider = registry.payments_provider_for(domain_name)
-          return {} unless provider
-
-          verbs = verbs_of(provider, Bluebook::Capabilities::PAYMENTS, :initiate, :succeeded, :failed)
-          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:initiate]),
-            **marked_states(provider, Bluebook::Capabilities::PAYMENTS, :holds_seat),
-            **all_words(provider, Bluebook::Capabilities::PAYMENTS) }
-        end
-
-        # Which chapter owns the checkout boundary (`Registry#checkout_provider_for`); `{}` if
-        # none does.
-        #
-        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
-        # @param domain_name [String] the domain to export the checkout binding for
-        # @return [Hash{Symbol => Object}] `:provider` (name) and, when declared,
-        #   `:webhook_tolerance` and `:session_hold` (whole seconds); `{}` if nothing this
-        #   domain attaches provides checkout
-        def checkout(registry, domain_name)
-          provider = registry.checkout_provider_for(domain_name)
-          return {} unless provider
-
-          { provider: provider.name, **all_durations(provider, Bluebook::Capabilities::CHECKOUT) }
+        # @param domain_name [String] the domain to export the capabilities for
+        # @return [Hash{String => Hash{Symbol => Object}}] each capability's name, mapped to
+        #   `:provider` (the bluebook's name) and one resolved value per key; `{}` if nothing
+        #   loaded declares one
+        def provides(registry, domain_name)
+          package_capabilities(registry).to_h do |capability|
+            provider = registry.vendored_provider_for(domain_name, capability)
+            values = provider.provision(capability).transform_values do |verb|
+              Bluebook::Capabilities.resolved_value(provider, verb)
+            end
+            [capability, { provider: provider.name, **values }]
+          end
         end
 
         private
@@ -189,9 +87,16 @@ module Hecks
           keys.to_h { |key| [key, provider.provided_verb(capability, key)] }
         end
 
-        # Each name in `names` mapped to the leading aggregate of the verb its key names in `verbs`.
-        def aggregates_of(verbs, names)
-          names.transform_values { |key| aggregate_of(verbs[key]) }
+        # Every capability name a loaded bluebook provides that the language defines no contract
+        # for.
+        def package_capabilities(registry)
+          provided_capabilities(registry).reject { |capability| Bluebook::Capabilities.language_defined?(capability) }
+        end
+
+        # Every capability name a loaded bluebook provides, once each, sorted.
+        def provided_capabilities(registry)
+          declarations = registry.bluebooks.values
+          declarations.flat_map { |declaration| declaration.provides.map(&:capability) }.uniq.sort
         end
 
         # The leading aggregate name of a qualified verb, or `nil` when there is no verb.

data/lib/hecks/projector/exporter/plugins.rb

@@ -0,0 +1,55 @@
+require "base64"
+require "digest"
+
+module Hecks
+  module Projector
+    module Exporter
+      # The wasm plugins a registry loaded, for the IR's `plugins` key: everything a host needs to
+      # answer a plugin's queries without the bluebook of the bluebook that declares them. The
+      # module itself rides in the IR, so every deploy that ships the IR ships the plugin too.
+      module Plugins
+        # Every plugin adapter in a registry, by name.
+        #
+        # @param registry [Runtime::Registry] the loaded registry
+        # @return [Array<Hash{String => Object}>] `"adapter"`, `"runs"`, `"sha256"` and `"module"`
+        #   (the module's bytes, base64), and `"queries"`: each answered question with
+        #   `"references"`, its `reference_to` arguments mapped to the qualified aggregate each
+        #   names
+        def plugins(registry)
+          found = registry.adapters.values.select(&:plugin?)
+          found.sort_by(&:name).map { |adapter| plugin_hash(registry, adapter) }
+        end
+
+        def plugin_hash(registry, adapter)
+          bytes = File.binread(adapter.plugin_path)
+          {
+            "adapter" => adapter.name,
+            "runs"    => adapter.runs,
+            "queries" => adapter.answered_queries.map { |question| plugin_query(registry, question) },
+            "sha256"  => Digest::SHA256.hexdigest(bytes),
+            "module"  => Base64.strict_encode64(bytes)
+          }
+        end
+
+        # One answered question and its reference arguments; a question no loaded bluebook declares
+        # carries none, and the host refuses it the way the runtime would.
+        def plugin_query(registry, question)
+          declaration_name, rest = question.split("::", 2)
+          aggregate_name, query_name = rest.split(".", 2)
+          aggregate = registry.bluebook(declaration_name)&.aggregate(aggregate_name)
+          query = aggregate&.query(query_name)
+          { "question" => question, "references" => references(declaration_name, aggregate, query) }
+        end
+
+        def references(declaration_name, aggregate, query)
+          return {} unless query
+
+          query.attributes.select(&:reference?).to_h do |attribute|
+            target = attribute.target_aggregate || aggregate
+            [attribute.name.to_s, "#{declaration_name}::#{target.hecks_name}"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/exporter.rb

@@ -2,6 +2,7 @@ require "json"
 require_relative "../ports/persistence"
 require_relative "exporter/adapters"
 require_relative "exporter/bindings"
+require_relative "exporter/plugins"
 require_relative "exporter/translations"
 require_relative "exporter/worlds"
 
@@ -76,6 +77,7 @@ module Hecks
 
       extend Adapters
       extend Bindings
+      extend Plugins
       extend Translations
       extend Worlds
     end

data/lib/hecks/projector/narrate_projector/commands.rb

@@ -61,7 +61,7 @@ module Hecks
           refs = command.attributes.select(&:reference?)
           return nil if refs.empty?
 
-          "It's aimed at one existing #{NarrateProjector.to_sentence_list(refs.map { |r| r.type.target_name })}, by id."
+          "It's aimed at one existing #{NarrateProjector.to_sentence_list(refs.map(&:target_name))}, by id."
         end
 
         def command_conditions_sentence(command, holder)
@@ -94,9 +94,10 @@ module Hecks
         def lifecycle_conditions(command, 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
           return [] if froms.empty?
 
           states = NarrateProjector.to_sentence_list(froms.map { |f| "`#{f}`" }, conj: "or")

data/lib/hecks/projector/narrate_projector/reactions.rb

@@ -1,11 +1,11 @@
 module Hecks
   module Projector
     module NarrateProjector
-      # The prose for what a chapter causes on its own: its policies and its sagas.
+      # The prose for what a bluebook causes on its own: its policies and its sagas.
       module Reactions
         module_function
 
-        # The "Reactions" section, or `nil` when the chapter has no policies or sagas.
+        # The "Reactions" section, or `nil` when the bluebook has no policies or sagas.
         def narrative(bluebook, depth)
           return nil if bluebook.policies.empty? && bluebook.process_managers.empty?
 

data/lib/hecks/projector/narrate_projector.rb

@@ -10,9 +10,9 @@ module Hecks
 
       # Projects `bluebook` as prose; `options[:heading]` sets the top heading level.
       #
-      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @param bluebook [Bluebook::Behaviour::Bluebook] the bluebook to narrate
       # @param options [Hash] `:heading` (Integer, default 1) and `:aggregate` (narrows to one
-      #   aggregate, omitting the chapter intro and reactions)
+      #   aggregate, omitting the bluebook intro and reactions)
       # @return [String] Markdown prose ending in a newline
       # @raise [Runtime::NotFound] if `options[:aggregate]` names no declared aggregate
       def call(bluebook:, options: {})
@@ -20,7 +20,7 @@ module Hecks
         only  = options[:aggregate]
 
         sections = []
-        sections << chapter_intro(bluebook, depth) unless only
+        sections << bluebook_intro(bluebook, depth) unless only
         sections.concat(aggregate_narratives(bluebook, only, only ? depth : depth + 1))
         sections << Reactions.narrative(bluebook, depth + 1) unless only
         "#{sections.compact.join("\n\n").rstrip}\n"
@@ -31,15 +31,16 @@ module Hecks
         Array(DocsProjector.aggregates(bluebook, only)).map { |aggregate| aggregate_narrative(aggregate, depth) }
       end
 
-      def chapter_intro(bluebook, depth)
+      def bluebook_intro(bluebook, depth)
         names = bluebook.aggregates.map(&:hecks_name)
-        parts = [DocsProjector.h(depth, bluebook.name), bluebook.vision, chapter_meta(bluebook)]
+        parts = [DocsProjector.h(depth, bluebook.name), bluebook.vision, bluebook_meta(bluebook)]
         parts << "It's told through #{to_sentence_list(names)}." unless names.empty?
         parts.compact.join("\n\n")
       end
 
-      # The chapter's classification and former name as one paragraph, or `nil` when it has neither.
-      def chapter_meta(bluebook)
+      # The bluebook's classification and former name as one paragraph, or `nil` when it has
+      # neither.
+      def bluebook_meta(bluebook)
         meta = []
         meta << "This is a #{bluebook.classification} domain." if bluebook.classification
         meta << "It was formerly known as `#{bluebook.formerly_known_as}`." if bluebook.formerly_known_as
@@ -63,7 +64,7 @@ module Hecks
         refs = aggregate.attributes.select(&:reference?)
         return nil if refs.empty?
 
-        targets = refs.map { |r| "#{a_or_an(r.type.target_name)} #{r.type.target_name}" }
+        targets = refs.map { |r| "#{a_or_an(r.target_name)} #{r.target_name}" }
         "Each one is linked to #{to_sentence_list(targets)}."
       end
 

data/lib/hecks/projector/target.rb

@@ -17,8 +17,8 @@ module Hecks
       #
       # @param key [String, Symbol] key to register `self` under
       # @param requires [Module, Array<Module>, nil] capability module(s) required;
-      #   nil/empty means `Bluebook::Behaviour::Chapter`
-      # @param declares [String, Symbol, Array, nil] aggregate name(s) the chapter must declare
+      #   nil/empty means `Bluebook::Behaviour::Bluebook`
+      # @param declares [String, Symbol, Array, nil] aggregate name(s) the bluebook must declare
       # @param emits [Symbol] :artifact (a Hash/String, the default) or :files (a path => tree)
       # @param needs_world [Boolean] true refuses a call made with no `world:` bindings
       # @return [Symbol] the registered key
@@ -37,11 +37,11 @@ module Hecks
       # @return [Symbol, nil] the key given to `projects_as`, or nil before it is called
       def projection_key = @projection_key
 
-      # Empty means "a chapter" — resolved here rather than as a default
-      # argument, because Behaviour::Chapter is not loaded yet when this
+      # Empty means "a bluebook" — resolved here rather than as a default
+      # argument, because Behaviour::Bluebook is not loaded yet when this
       # file is.
       #
-      # @return [Array<String, Symbol>] aggregate names the chapter must declare; empty
+      # @return [Array<String, Symbol>] aggregate names the bluebook must declare; empty
       #   for none
       def projection_declares = @projection_declares || []
 
@@ -62,7 +62,7 @@ module Hecks
       # so there is no second spelling to drift.
       #
       # @return [Symbol] `:export` if it needs a world, `:meta` if it needs a
-      #   chapter declaring particular aggregates, otherwise `:projection`
+      #   bluebook declaring particular aggregates, otherwise `:projection`
       def projection_category
         return :export if projection_needs_world?
 
@@ -70,12 +70,12 @@ module Hecks
       end
 
       # Names the capability module(s) a construct must satisfy, defaulting
-      # to plain chapter-hood when `projects_as` named none.
+      # to plain bluebook-hood when `projects_as` named none.
       #
       # @return [Array<Module>] required capability modules
       def projection_requires
         req = @projection_requires
-        req.nil? || req.empty? ? [Bluebook::Behaviour::Chapter] : req
+        req.nil? || req.empty? ? [Bluebook::Behaviour::Declaration] : req
       end
     end
   end