hecks 1.3.0 → 1.5.0

data/lib/hecks/projector/narrate_projector.rb

@@ -3,20 +3,22 @@ require_relative "../forms/field_shape"
 
 module Hecks
   module Projector
-    # A BLUEBOOK, PROJECTED AS PROSE AN SME CAN READ BACK AND CONFIRM.
+    # A bluebook, projected as prose an SME can read back and confirm.
     #
-    # WHAT THIS IS FOR. `DocsProjector` already answers "what can I call and
-    # what does it want" for the person implementing against a domain —
-    # tables of arguments, shapes, refusal reasons. That is the wrong
-    # register for the person who can actually say whether the domain is
-    # RIGHT: the subject-matter expert who knows what an account is and has
-    # never read a markdown table in their life. This projects the same IR
-    # as sentences instead — "Debit — take money out. Issued by a Teller. It
-    # only goes through if the balance covers it." — so a domain can be
-    # read back to the person who can validate it without them learning the
-    # DSL first.
+    # ## What this is for
     #
-    # SAME SOURCE, SAME GUARANTEE `DocsProjector` gives: nothing here is
+    # `DocsProjector` already answers "what can I call and what does it
+    # want" for the person implementing against a domain — tables of
+    # arguments, shapes, refusal reasons. That is the wrong register for
+    # the person who can actually say whether the domain is right: the
+    # subject-matter expert who knows what an account is and has never
+    # read a markdown table in their life. This projects the same IR as
+    # sentences instead — "Debit — take money out. Issued by a Teller.
+    # It only goes through if the balance covers it." — so a domain can
+    # be read back to the person who can validate it without them
+    # learning the DSL first.
+    #
+    # Same source, same guarantee `DocsProjector` gives: nothing here is
     # invented. Every sentence quotes a `description`, `goal`, or `given`
     # already declared in the chapter; where a chapter says nothing, this
     # says nothing rather than manufacturing a sentence out of an
@@ -24,17 +26,30 @@ module Hecks
     # (`Projector.call(:narrate, bluebook: ...)`), same aggregate-scoping
     # via `options[:aggregate]`.
     #
-    # WHAT IT DOES NOT DO: replace `DocsProjector`. A shape table still says
-    # "id of a Customer" more precisely than any sentence would, and an
-    # implementer still wants that. This is the other document the same IR
-    # is owed — one written for the reader who is being asked "is this
-    # right?", not "how do I call it?"
+    # ## What it does not do
+    #
+    # Replace `DocsProjector`. A shape table still says "id of a
+    # Customer" more precisely than any sentence would, and an
+    # implementer still wants that. This is the other document the same
+    # IR is owed — one written for the reader who is being asked "is
+    # this right?", not "how do I call it?"
     module NarrateProjector
       module_function
 
+      # Projects `bluebook` as prose an SME can read back and confirm.
+      #
       # `options[:heading]` sets the top heading level, exactly as
       # `DocsProjector` does — so this, too, can be spliced into a larger
       # document rather than always starting at H1.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @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 narrative to one
+      #   aggregate, omitting the chapter intro and reactions sections
+      # @return [String] the narrative, as Markdown prose, ending in a newline
+      # @raise [Runtime::NotFound] if `options[:aggregate]` names no aggregate `bluebook`
+      #   declares
       def call(bluebook:, options: {})
         depth = (options[:heading] || 1).to_i
         only  = options[:aggregate]
@@ -50,6 +65,12 @@ module Hecks
 
       # ── the chapter ───────────────────────────────────────────────────
 
+      # Narrates the chapter-level intro: its vision, classification, former
+      # name, and the aggregates it's told through.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @param depth [Integer] the heading level for the chapter's own title
+      # @return [String] the intro's Markdown prose
       def chapter_intro(bluebook, depth)
         parts = [DocsProjector.h(depth, bluebook.name)]
         parts << bluebook.vision if bluebook.vision
@@ -66,6 +87,12 @@ module Hecks
 
       # ── one aggregate ─────────────────────────────────────────────────
 
+      # Narrates one aggregate: its description, identity, references,
+      # lifecycle, commands, queries, and nested entities.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate to narrate
+      # @param depth [Integer] the heading level for the aggregate's own title
+      # @return [String] the aggregate's Markdown prose
       def aggregate_narrative(aggregate, depth)
         parts = [DocsProjector.h(depth, aggregate.hecks_name)]
         parts << aggregate.description if aggregate.description
@@ -86,12 +113,23 @@ module Hecks
         parts.compact.join("\n\n")
       end
 
+      # Names how a holder is identified.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to describe
+      # @return [String, nil] a sentence naming `holder`'s identity fields, or nil if
+      #   it declares none
       def identity_sentence(holder)
         return nil if holder.identity_heads.empty?
 
         "Every #{holder.hecks_name} is identified by its #{to_sentence_list(holder.identity_heads.map { |h| "`#{h}`" })}."
       end
 
+      # Narrates one entity nested under `aggregate`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the entity's own owning aggregate
+      # @param entity [Bluebook::Entity] the entity to narrate
+      # @param depth [Integer] the heading level for the entity's own title
+      # @return [String] the entity's Markdown prose
       def entity_narrative(aggregate, entity, depth)
         parts = [DocsProjector.h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})")]
         parts << entity.description if entity.description
@@ -106,6 +144,11 @@ module Hecks
 
       # ── the machine ───────────────────────────────────────────────────
 
+      # Narrates a holder's own lifecycle transitions.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to describe
+      # @return [String, nil] a sentence per lifecycle transition, or nil if `holder`
+      #   declares no lifecycle
       def lifecycle_narrative(holder)
         lifecycle = holder.lifecycle or return nil
 
@@ -120,6 +163,13 @@ module Hecks
 
       # ── the verbs ─────────────────────────────────────────────────────
 
+      # Narrates every command a holder declares.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+      #   commands to narrate
+      # @param depth [Integer] the heading level for the "What can happen" section
+      # @return [String, nil] the section's Markdown prose, or nil if `holder`
+      #   declares no command
       def verbs_narrative(holder, depth)
         return nil if holder.commands.empty?
 
@@ -128,7 +178,7 @@ module Hecks
         "#{header}\n\n#{body}"
       end
 
-      # ONE PARAGRAPH, BUILT FROM INDEPENDENT SENTENCES — each sentence
+      # One paragraph, built from independent sentences — each sentence
       # below states one unrelated fact about `command` (its goal, who
       # issues it, whether it creates the holder, what it takes, what it
       # references, what gates it, what it guarantees, what it emits), in
@@ -136,6 +186,10 @@ module Hecks
       # sentence depends on anything before it. Same nil-or-string +
       # `compact.join` shape `aggregate_narrative`/`entity_narrative`
       # already use above for the identical reason.
+      #
+      # @param command [Bluebook::Command] the command to narrate
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [String] the command's own paragraph
       def command_paragraph(command, holder)
         [
           command_headline_sentence(command),
@@ -149,31 +203,48 @@ module Hecks
         ].compact.join(" ")
       end
 
-      # THE GOAL, VERBATIM — same rule `DocsProjector` holds to: quoted
+      # The goal, verbatim — same rule `DocsProjector` holds to: quoted
       # exactly as declared, not recased to fit mid-sentence, because the
       # promise this whole projector makes is that a sentence here is a
       # sentence the chapter actually wrote.
+      #
+      # @param command [Bluebook::Command] the command to name
+      # @return [String] the command's own bold name, plus its goal if it declares one
       def command_headline_sentence(command)
         "**#{command.hecks_name}**#{command.goal ? " — #{command.goal}." : '.'}"
       end
 
+      # Names who issues a command.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence naming who issues `command`, or nil if it
+      #   declares no role
       def command_role_sentence(command)
         return nil unless command.role
 
         "Issued by #{a_or_an(command.role)} #{command.role}."
       end
 
-      # `acts_on.nil?`, NOT `creates?` — `creates?` answers true for every
-      # verb an ENTITY declares (it never references itself; see
+      # `acts_on.nil?`, not `creates?` — `creates?` answers true for every
+      # verb an entity declares (it never references itself; see
       # `Command#acts_on`'s own comment), so reading it directly here would
       # tell an SME that `LedgerEntry.Amend` brings a new ledger entry into
       # being, which is exactly backwards.
+      # @param command [Bluebook::Command] the command to check
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [String, nil] a sentence saying `command` creates `holder`, or nil if
+      #   `command` acts on an existing record instead
       def command_creation_sentence(command, holder)
         return nil unless command.acts_on.nil?
 
         "This is how a new #{holder.hecks_name} comes into being."
       end
 
+      # Lists a command's own non-reference arguments.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence listing `command`'s non-reference arguments,
+      #   or nil if it declares none
       def command_arguments_sentence(command)
         arguments = command.attributes.reject(&:reference?)
         return nil if arguments.empty?
@@ -181,6 +252,11 @@ module Hecks
         "It takes #{to_sentence_list(arguments.map { |a| Forms::Humanize.label(a.name.to_s).downcase })}."
       end
 
+      # Names what a command references.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence naming what `command` references, or nil if
+      #   it declares no reference argument
       def command_references_sentence(command)
         refs = command.attributes.select(&:reference?)
         return nil if refs.empty?
@@ -188,6 +264,12 @@ module Hecks
         "It's aimed at one existing #{to_sentence_list(refs.map { |r| r.type.target_name })}, by id."
       end
 
+      # Lists a command's own required conditions.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [String, nil] a sentence listing every required condition, or nil if
+      #   `command` declares none
       def command_conditions_sentence(command, holder)
         conditions = conditions_of(command, holder)
         return nil if conditions.empty?
@@ -195,6 +277,11 @@ module Hecks
         "It only goes through if #{conditions.join('; ')}."
       end
 
+      # Lists what a command guarantees when it succeeds.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence listing `command`'s own `ensures`, or nil if
+      #   it declares none
       def command_guarantees_sentence(command)
         guarantees = command.ensures.map(&:description)
         return nil if guarantees.empty?
@@ -202,18 +289,27 @@ module Hecks
         "When it succeeds: #{guarantees.join('; ')}."
       end
 
+      # Names what a command records.
+      #
+      # @param command [Bluebook::Command] the command to describe
+      # @return [String, nil] a sentence naming what `command` records, or nil if it
+      #   emits nothing
       def command_emits_sentence(command)
         return nil if command.emits.empty?
 
         "It records `#{command.emits.join('`, `')}` as a fact."
       end
 
-      # EVERY REQUIRED CONDITION, STATED AS SOMETHING THAT MUST BE TRUE —
+      # Every required condition, stated as something that must be true —
       # the same three sources `DocsProjector#refusals_of` reads (the
       # lifecycle edge, a reference's existence, and the command's own
       # `given`s), but kept positive rather than phrased as a refusal
       # reason. "Refused unless not X" is a sentence a reader has to
       # invert in their head; "only goes through if X" is not.
+      #
+      # @param command [Bluebook::Command] the command to gather conditions for
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [Array<String>] every required condition, stated positively
       def conditions_of(command, holder)
         conditions = []
 
@@ -234,6 +330,12 @@ module Hecks
 
       # ── the reads ─────────────────────────────────────────────────────
 
+      # Narrates every query as one line per question.
+      #
+      # @param queries [Array<Bluebook::Query>] the queries to narrate
+      # @param holder_name [String] the queries' own holder's name
+      # @param depth [Integer] the heading level for the "Questions you can ask" section
+      # @return [String, nil] the section's Markdown prose, or nil if `queries` is empty
       def queries_narrative(queries, holder_name, depth)
         return nil if queries.empty?
 
@@ -241,7 +343,7 @@ module Hecks
         lines = queries.map do |query|
           shape   = query.to_h
           takes   = Array(shape[:attributes]).map { |a| Forms::Humanize.label(a[:name].to_s).downcase }
-          # `w[:value]` ALREADY WEARS ITS OWN QUOTES OR COLON — it is a
+          # `w[:value]` already wears its own quotes or colon — it is a
           # `Literal.render`ed string (see lib/hecks/literal.rb), not a raw
           # Ruby value, so wrapping it in `.inspect` here would quote an
           # already-quoted string a second time.
@@ -257,12 +359,23 @@ module Hecks
         "#{header}\n\n#{lines.join("\n")}"
       end
 
+      # Translates a query comparator into plain English.
+      #
+      # @param comparator [String, Symbol] a where-clause comparator, such as `:eq`
+      # @return [String] the comparator in plain words, or `comparator.to_s` verbatim
+      #   for one this file has no rendering rule for
       def op_words(comparator)
         { eq: "is", lt: "under", lte: "at most", gt: "over", gte: "at least" }[comparator.to_s.to_sym] || comparator.to_s
       end
 
       # ── what happens on its own ───────────────────────────────────────
 
+      # Narrates what happens on its own: every policy and every saga.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to narrate
+      # @param depth [Integer] the heading level for the "Reactions" section
+      # @return [String, nil] the section's Markdown prose, or nil if `bluebook`
+      #   declares no policy and no process manager
       def reactions_narrative(bluebook, depth)
         return nil if bluebook.policies.empty? && bluebook.process_managers.empty?
 
@@ -286,8 +399,16 @@ module Hecks
 
       # Both now live in `Naming` (a second projection, the glossary,
       # needed them); kept here as names so this file reads as it did.
+      #
+      # @param items [Array<#to_s>] items to join, in order
+      # @param conj [String] conjunction placed before the last item
+      # @return [String] the joined sentence fragment, `""` for an empty `items`
       def to_sentence_list(items, conj: "and") = Naming.to_sentence_list(items, conj: conj)
 
+      # Picks the English indefinite article for a word.
+      #
+      # @param word [String, Symbol] the word the article precedes
+      # @return [String] `"a"` or `"an"`
       def a_or_an(word) = Naming.a_or_an(word)
     end
   end

data/lib/hecks/projector/target.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Projector
-    # WHAT MAKES A MODULE A PROJECTION TARGET. `Projector.register` has
+    # What makes a module a projection target. `Projector.register` has
     # always accepted anything answering `call(bluebook:, options:)` —
     # this only removes the second step, so a target declares its own key
     # beside its own implementation instead of being registered from
@@ -15,20 +15,20 @@ module Hecks
     #     def call(bluebook:, options: {}) = { ... }
     #   end
     #
-    # NAMED `Target`, NOT `Projection`, on purpose. "Projection" already
+    # Named `Target`, not `Projection`, on purpose. "Projection" already
     # means two other things in this codebase: `Ports::Projection` is
     # read-model catch-up (events folded into view state), and `bin/project`
     # forces that catch-up by hand. Neither has anything to do with
     # "canonical IR in, external artifact out". A third meaning under the
     # same word would make the two impossible to grep apart — and from a
-    # domain's point of view `project(X)` really does read as "project TO
+    # domain's point of view `project(X)` really does read as "project to
     # a target", so the narrower word is also the more accurate one.
     module Target
       # Registering at declaration time means `require`ing a target is
       # the whole of installing it — there is no separate manifest that
       # can silently disagree about which targets exist.
       #
-      # `requires:` NAMES A CAPABILITY, not a shape word.
+      # `requires:` names a capability, not a shape word.
       #
       # This began as `from: :chapter` / `from: :any` — two hand-kept
       # symbols, admitted by duck-typing on `.aggregates`, which is a
@@ -44,32 +44,43 @@ module Hecks
       # It also composes: a projection needing two capabilities names
       # both, instead of a third symbol being invented for the pair.
       #
-      # THE FAIL-QUIET THIS CLOSES, unchanged in substance: every
-      # construct emits its own IR, so handing a projector an AGGREGATE
+      # The fail-quiet this closes, unchanged in substance: every
+      # construct emits its own IR, so handing a projector an aggregate
       # instead of a chapter is the natural thing to try. `bluebook:` was
-      # only ever a PARAMETER NAME, never a contract. `:oidc` failed
+      # only ever a parameter name, never a contract. `:oidc` failed
       # loudly (no `aggregates` method), but `:shape` returned
       # `{"name" => "Order", "aggregates" => []}` — well-formed,
       # confident, and wrong.
-      # `declares:` NAMES AN AGGREGATE THE CHAPTER MUST HAVE.
+      # `declares:` names an aggregate the chapter must have.
       #
-      # A capability says what a construct can DO; this says what it must
-      # CARRY. `:vocabulary` needs a chapter declaring a Vocabulary
-      # aggregate, `:parser_table` one declaring Syntax — and both used
-      # to state that as a `raise` in their own body, which is a
-      # requirement written as behaviour instead of declared. Stated
-      # here, the registry refuses before the projection runs and the
-      # projection stops carrying a guard about its own admission.
-      # `emits:` SAYS WHAT KIND OF ARTIFACT COMES BACK.
+      # A capability says what a construct can do; this says what it must
+      # carry. `:vocabulary` needs a chapter declaring a Vocabulary
+      # aggregate, `:parser_table` one declaring Syntax — declared here
+      # rather than as a `raise` in the projection's own body, so the
+      # requirement is stated instead of written as behaviour. The
+      # registry refuses before the projection runs, so the projection
+      # itself no longer carries a guard about its own admission.
+      # `emits:` says what kind of artifact comes back.
       #
       # `:artifact` (the default) is one thing — a Hash, or a String.
-      # `:files` is a TREE: a Hash of relative path => contents, which is
+      # `:files` is a tree: a Hash of relative path => contents, which is
       # what a reference-page or codegen projection produces.
       #
       # Declared rather than sniffed, deliberately. Inferring a tree from
       # an ordinary Hash is guesswork — `{"name" => "Pizzas"}` is
       # indistinguishable from a one-file tree — so `write` asks what the
       # projection said rather than inspecting what it returned.
+      # Registers `self` as a projection target under `key`, and stores the
+      # capability and aggregate requirements `admits!` later checks against.
+      #
+      # @param key [String, Symbol] the key to register `self` under (converted to a symbol)
+      # @param requires [Module, Array<Module>, nil] capability module(s) a construct must
+      #   satisfy; nil or empty means `Bluebook::Behaviour::Chapter`
+      # @param declares [String, Symbol, Array<String, Symbol>, nil] aggregate name(s) the
+      #   chapter must declare; nil means none
+      # @param emits [Symbol] the kind of artifact `self` returns: `:artifact` (the default,
+      #   a single Hash or String) or `:files` (a path => contents tree)
+      # @return [Symbol] the registered key
       def projects_as(key, requires: nil, declares: nil, emits: :artifact)
         @projection_emits    = emits
         @projection_key      = key.to_sym
@@ -79,15 +90,28 @@ module Hecks
         @projection_key
       end
 
+      # Gives the key this target registered under.
+      #
+      # @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
+      # Empty means "a chapter" — resolved here rather than as a default
       # argument, because Behaviour::Chapter is not loaded yet when this
       # file is.
+      #
+      # @return [Array<String, Symbol>] aggregate names the chapter must declare; empty
+      #   for none
       def projection_declares = @projection_declares || []
 
+      # Gives the kind of artifact this target returns.
+      #
+      # @return [Symbol] the kind of artifact `self` returns: `:artifact` or `:files`
       def projection_emits = @projection_emits || :artifact
 
+      # Names the capability module(s) a construct must satisfy, defaulting
+      # to plain chapter-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