hecks 2.8.0 → 2.9.0

data/lib/hecks/projector/narrate_projector.rb

@@ -3,53 +3,18 @@ require_relative "../forms/field_shape"
 
 module Hecks
   module Projector
-    # 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.
-    #
-    # 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
-    # identifier. Registered as `:narrate` beside `:docs`, same call shape
-    # (`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?"
+    # A bluebook projected as prose an SME can read back and confirm.
+    # Every sentence quotes a declared `description`, `goal` or `given`; nothing is invented.
     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.
+      # Projects `bluebook` as prose; `options[:heading]` sets the top heading level.
       #
       # @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
+      # @param options [Hash] `:heading` (Integer, default 1) and `:aggregate` (narrows to one
+      #   aggregate, omitting the chapter 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: {})
         depth = (options[:heading] || 1).to_i
         only  = options[:aggregate]
@@ -63,14 +28,6 @@ module Hecks
         "#{sections.compact.join("\n\n").rstrip}\n"
       end
 
-      # ── 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
@@ -85,14 +42,6 @@ module Hecks
         parts.join("\n\n")
       end
 
-      # ── 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
@@ -113,23 +62,12 @@ 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
@@ -142,13 +80,6 @@ module Hecks
         parts.compact.join("\n\n")
       end
 
-      # ── 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
 
@@ -161,15 +92,6 @@ module Hecks
         sentences.join(" ")
       end
 
-      # ── 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?
 
@@ -178,18 +100,7 @@ module Hecks
         "#{header}\n\n#{body}"
       end
 
-      # 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
-      # the fixed order a reader expects them; nothing after the first
-      # 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
+      # Each sentence states one independent fact, so nil-or-string plus `compact.join` suffices.
       def command_paragraph(command, holder)
         [
           command_headline_sentence(command),
@@ -203,48 +114,25 @@ module Hecks
         ].compact.join(" ")
       end
 
-      # 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
+      # The goal is quoted exactly as declared, never recased to fit mid-sentence.
       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
-      # `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
+      # `acts_on.nil?`, not `creates?`: `creates?` is true for every entity verb, which would
+      # wrongly say `LedgerEntry.Amend` creates a new ledger entry.
       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?
@@ -252,11 +140,6 @@ 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?
@@ -264,12 +147,6 @@ 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?
@@ -277,11 +154,6 @@ 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?
@@ -289,27 +161,14 @@ 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 —
-      # 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
+      # Required conditions stated positively ("only goes through if X"), from the lifecycle
+      # edge and the command's `given`s.
       def conditions_of(command, holder)
         conditions = []
 
@@ -328,14 +187,6 @@ module Hecks
         conditions + command.givens.map(&:description)
       end
 
-      # ── 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?
 
@@ -343,10 +194,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
-          # `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.
+          # `w[:value]` is already `Literal.render`ed (quoted), so no `.inspect`.
           filters = Array(shape[:wheres]).map { |w| "`#{w[:field]}` #{op_words(w[:op])} #{w[:value]}" }
 
           sentence = "- **#{query.hecks_name}**"
@@ -359,23 +207,10 @@ 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?
 
@@ -395,19 +230,10 @@ module Hecks
         parts.join("\n\n")
       end
 
-      # ── small sentence carpentry ──────────────────────────────────────
-
-      # 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.
+      # Picks the article for `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

data/lib/hecks/projector/target.rb

@@ -1,89 +1,26 @@
 module Hecks
   module Projector
-    # 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
-    # somewhere else that has to be kept in sync with it.
+    # A projection target declares its own registration key beside its own
+    # implementation, instead of a separate registry entry that can drift.
     #
     #   module Hecks::Projections::OIDC
     #     extend Hecks::Projector::Target
     #     projects_as :oidc
-    #
-    #     module_function
-    #
-    #     def call(bluebook:, options: {}) = { ... }
+    #     def self.call(bluebook:, options: {}) = { ... }
     #   end
     #
-    # 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
-    # a target", so the narrower word is also the more accurate one.
+    # Named `Target`, not `Projection`, which already means read-model catch-up elsewhere.
     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.
-      #
-      # This began as `from: :chapter` / `from: :any` — two hand-kept
-      # symbols, admitted by duck-typing on `.aggregates`, which is a
-      # guess at what "is a chapter" means. The capabilities were already
-      # real by then: `Hecks::IR` is the ability to emit IR (its own
-      # header says so), and `Behaviour::Chapter` is the ability to answer
-      # as a chapter. So a projection names the module it needs, and
-      # admission is a genuine check rather than a proxy for one.
-      #
-      #   projects_as :ir,         requires: Hecks::IR
-      #   projects_as :vocabulary                              # chapter, the default
-      #
-      # 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
-      # instead of a chapter is the natural thing to try. `bluebook:` was
-      # 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.
-      #
-      # 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 carries no 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
-      # 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.
+      # Registers `self` as a projection target under `key`; the registry
+      # checks `requires`/`declares` before a projection ever runs, so a
+      # projection carries no admission guard of its own.
       #
-      # @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)
-      # @param needs_world [Boolean] whether `self` is an export — a target that reads a
-      #   domain's `.world`/`.hecksagon` bindings, not only its declaration. `false` (the
-      #   default) for an ordinary projection; `true` refuses a `Projector.call` made with
-      #   no `world:`.
+      # @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
+      # @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
       def projects_as(key, requires: nil, declares: nil, emits: :artifact, needs_world: false)
         @projection_emits       = emits