hecks 1.4.0 → 1.5.0

data/lib/hecks/projector/narrate_projector.rb

@@ -5,16 +5,18 @@ 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.
+    # ## 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`
@@ -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?
 
@@ -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),
@@ -153,10 +207,18 @@ module Hecks
       # 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
 
@@ -168,12 +230,21 @@ module Hecks
       # `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,6 +289,11 @@ 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?
 
@@ -214,6 +306,10 @@ module Hecks
       # `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?
 
@@ -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

@@ -55,11 +55,11 @@ module Hecks
       #
       # 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.
+      # 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.
@@ -70,6 +70,17 @@ module Hecks
       # 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
       # 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

data/lib/hecks/projector.rb

@@ -17,8 +17,11 @@ module Hecks
   # every real projection target (Rust/UL/OIDC all project one domain at
   # a time), and deliberately narrower than `Exporter.call`'s own
   # multi-domain shape.
-  # Three kinds of "PROJECT", told apart by what they need as input.
-  # Only the first belongs in this registry.
+  #
+  # ## Three kinds of "project"
+  #
+  # Told apart by what they need as input. Only the first belongs in this
+  # registry.
   #
   #   a projection takes a chapter's declaration and answers something
   #   that describes the domain: its IR, its storage shape, an OIDC scope
@@ -42,8 +45,10 @@ module Hecks
   #   dispatches. Converting it into this registry would be a category
   #   error, however much its name suggests otherwise.
   #
-  # **One word, three other meanings** — worth naming too, because grepping
-  # "projection" turns all of these up and none is the above:
+  # ## One word, three other meanings
+  #
+  # Worth naming too, because grepping "projection" turns all of these up
+  # and none is the above:
   #
   #   Ports::Projection    read-model catch-up, events folded into state
   #   bin/project          forces that catch-up by hand
@@ -61,14 +66,33 @@ module Hecks
     # deliberately unguarded: a spec re-registering a stub under the same
     # name between examples is the ordinary case, not a footgun to fence
     # against.
+    # Adds `projector` to the registry under `name`, replacing anything
+    # already registered there.
+    #
+    # @param name [String, Symbol] the key `projector` is looked up by (converted to a symbol)
+    # @param projector [Module, Class, #call] anything answering `call(bluebook:, options:)`
+    # @return [void]
     def register(name, projector)
       registry[name.to_sym] = projector
     end
 
+    # Runs the projector registered under `name` against `bluebook`,
+    # after refusing a construct it does not admit.
+    #
     # `bluebook:` is kept as the keyword because it is the shipped
     # spelling and every existing caller uses it — but what it accepts is
     # any construct that emits IR, and `admits!` is what decides whether
     # this target can actually take the one handed over.
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @param bluebook [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
+    #   IR-emitting construct to project
+    # @param options [Hash] projector-specific options, passed through unchanged
+    # @return [Object] whatever the projector's own `call` returns: typically a
+    #   `Hash`/`String` artifact, or a `Hash{String => String}` file tree
+    # @raise [UnknownProjector] if no projector is registered under `name`
+    # @raise [WrongConstruct] if `bluebook` lacks a capability or aggregate the
+    #   projector requires
     def call(name, bluebook:, options: {})
       projector = registry.fetch(name.to_sym) do
         raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
@@ -77,8 +101,9 @@ module Hecks
       projector.call(bluebook: bluebook, options: options)
     end
 
-    # A projection names the capabilities it needs; this refuses a
-    # construct that lacks one, before the projector runs.
+    # Refuses `construct` if it lacks a capability or declared aggregate
+    # `projector` requires. A projection names the capabilities it needs;
+    # this is what enforces that, before the projector runs.
     #
     # One check covers both shapes. An ordinary construct includes its
     # capabilities and a class-shaped one — Command, Entity, ValueObject
@@ -87,6 +112,16 @@ module Hecks
     # started as two checks on the assumption it would not; a spec
     # asserting the assumption failed, which is the only reason the
     # redundant half was noticed.
+    #
+    # @param name [String, Symbol] the projector's registered key, used in the message
+    #   when refusing
+    # @param projector [Module, Class, #call] the target being checked; consulted for
+    #   `projection_requires` and `projection_declares` when it answers them
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the chapter or
+    #   IR-emitting construct offered to the projector
+    # @return [void]
+    # @raise [WrongConstruct] if `construct` lacks a required capability, or the
+    #   chapter it is declares no aggregate the projector needs
     def admits!(name, projector, construct)
       needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
       missing = needed.reject { |capability| capable?(construct, capability) }
@@ -105,18 +140,38 @@ module Hecks
             "#{construct.name} declares no such aggregate."
     end
 
+    # Tells whether `construct` has the capability `admits!` requires of it.
+    #
+    # @param construct [Bluebook::Behaviour::Chapter, Hecks::IR] the construct to check
+    # @param capability [Module] the capability module to check for
+    # @return [Boolean] true if `construct` is a `capability`
     def capable?(construct, capability) = construct.is_a?(capability)
 
     # What kind of artifact a registered target emits — asked of the
     # projection rather than inferred from what it returned.
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @return [Symbol] `:files` for a path => contents tree, `:artifact` (the
+    #   default, including for an unregistered `name`) for a single Hash or String
     def emits_for(name)
       projector = registry.fetch(name.to_sym) { return :artifact }
       projector.respond_to?(:projection_emits) ? projector.projection_emits : :artifact
     end
 
+    # Tells whether a projector is registered under `name`.
+    #
+    # @param name [String, Symbol] the key to look up
+    # @return [Boolean] true if a projector is registered under `name`
     def registered?(name) = registry.key?(name.to_sym)
+
+    # Lists every key currently registered.
+    #
+    # @return [Array<Symbol>] every key currently registered
     def registered = registry.keys
 
+    # Gives the live registry, initializing it on first use.
+    #
+    # @return [Hash{Symbol => Module, Class, #call}] the live key => projector registry
     def registry
       @registry ||= {}
     end
@@ -126,6 +181,10 @@ module Hecks
     # (`:oidc`). Both resolve here, so the constant form is added
     # surface rather than a replacement — every `Projector.call(:ir, ...)`
     # written before this existed keeps working untouched.
+    #
+    # @param target [String, Symbol, #projection_key] a registered key, or a target
+    #   that declared its own key with `Target#projects_as`
+    # @return [String, Symbol] the key to call the target under
     def key_for(target)
       return target.projection_key if target.respond_to?(:projection_key) && target.projection_key
 
@@ -141,6 +200,11 @@ module Hecks
     # than from inspecting the artifact. A Hash of path => contents and a
     # Hash that simply happens to hold strings are the same object to
     # Ruby; only the projection knows which it meant.
+    #
+    # @param artifact [Hash, String] the projector's output; a file tree when `as: :files`
+    # @param out [String] the path to write to; a directory when `as: :files`
+    # @param as [Symbol] `:files` to write a tree, anything else to write one file
+    # @return [String, Array<String>] the path written, or every path written when `as: :files`
     def write(artifact, out, as: :artifact)
       return write_tree(artifact, out) if as == :files
 
@@ -150,6 +214,10 @@ module Hecks
 
     # Answers the paths written, in the order given — so a caller can
     # report what happened without re-deriving it from the tree.
+    #
+    # @param files [Hash{String => String}] relative path => contents
+    # @param directory [String] the directory to write the tree under
+    # @return [Array<String>] each file's full written path, in `files`' order
     def write_tree(files, directory)
       require "fileutils"
       files.map do |relative, contents|

data/lib/hecks/query_ir.rb

@@ -37,6 +37,11 @@ module Hecks
 
     module_function
 
+    # Reads the fields the language declares for one construct kind, from the grammar itself.
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Array<Symbol>] the attribute names the self-hosted meta-domain
+    #   grammar declares for `name`
     def meta_declared(name)
       Hecks::Bluebook::MetaValidator.grammar_registry
                                     .bluebook("Bluebook").aggregate(name).attributes.map(&:name)
@@ -47,6 +52,11 @@ module Hecks
     # for it — the same comparison spec/model_shape_conformance_spec.rb
     # makes, reusing its own Deviations data so this can never silently
     # drift from what that gate actually checks.
+    #
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @return [Hash{Symbol => Object}] `:name`, `:declared`, `:emitted`, plus
+    #   `:missing_from_ruby` and `:unaccounted_in_ruby` — each an `Array<Symbol>`
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
     def construct_diff(name)
       klass = CONSTRUCTS.fetch(name) do
         raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}"
@@ -72,6 +82,10 @@ module Hecks
         missing_from_ruby: accounted - emitted, unaccounted_in_ruby: unaccounted }
     end
 
+    # Diffs one or every construct kind at once.
+    #
+    # @param names [Array<String>] `CONSTRUCTS` keys to diff, every construct when empty
+    # @return [Array<Hash>] one `construct_diff` result per name
     def constructs(names = [])
       targets = names.empty? ? CONSTRUCTS.keys : names
       targets.map { |name| construct_diff(name) }
@@ -96,6 +110,10 @@ module Hecks
     # already a distinct object, whether it was block-declared or
     # bare-referenced — object identity carries no signal past that
     # point, for any construct, not just this one).
+    #
+    # @param registry [Runtime::Registry] the booted registry to walk
+    # @param chapter_name [String, nil] one chapter to walk, every booted chapter when nil
+    # @return [Array<Rule>]
     def collect_rules(registry, chapter_name = nil)
       rules = []
       chapters = chapter_name ? [registry.bluebook(chapter_name)] : registry.bluebooks.values
@@ -158,6 +176,10 @@ module Hecks
     # local_givens` reads it directly to group `collect_rules`' own
     # output by owner itself, the same reading `duplicates`' own
     # `declaration_count` makes.
+    #
+    # @param location [String] a `Rule#location`
+    # @return [String] the owning construct's path, with `" (declared)"` or a trailing
+    #   `.CommandName` segment stripped
     def owner_of(location)
       return location.sub(/ \(declared\)\z/, "") if location.end_with?(" (declared)")
 
@@ -188,6 +210,12 @@ module Hecks
     # `domains: []` means "the self-hosted meta-domain only" — pass real
     # domain directories explicitly to include them, or `nil` (the
     # default) for meta-domain plus every real example.
+    #
+    # @param domains [Array<String>, nil] domain root directories to scan; every real
+    #   example (`Codemod::EXAMPLE_ROOTS`) when nil, none beyond the meta-domain when `[]`
+    # @param include_meta [Boolean] whether to also scan the self-hosted meta-domain
+    # @return [Array<Hash>] one entry per duplicate group: `:kind`, `:description`,
+    #   `:canonical`, and `:locations` (`Array<String>`)
     def duplicates(domains: nil, include_meta: true)
       domains ||= Codemod::EXAMPLE_ROOTS
       all_rules = []
@@ -260,6 +288,9 @@ module Hecks
     # case above, before assuming a group naming two pieces under
     # different aggregates is fresh duplication rather than an already-
     # resolved chapter-wide reference.
+    #
+    # @param rules [Array<Rule>] one duplicate-key group's own rules
+    # @return [Integer] how many of `rules` are real, independent declarations
     def declaration_count(rules)
       declared = rules.select { |r| r.location.end_with?(" (declared)") }
       declared_owners = declared.to_set { |r| owner_of(r.location) }
@@ -282,6 +313,8 @@ module Hecks
     # `bin/hecks_query_ir_mcp` (an MCP tool result, itself a text
     # block) want the identical human-readable rendering; only the
     # outer framing differs (plain stdout vs. a JSON-RPC content array).
+    # @param diffs [Array<Hash>] `constructs`' own output
+    # @return [String] the human-readable rendering
     def format_constructs(diffs)
       diffs.map do |diff|
         lines = ["== #{diff[:name]} =="]
@@ -328,6 +361,12 @@ module Hecks
     # existing gate (`model_shape_conformance_spec.rb`,
     # `assembly_spec.rb`, `meta_domain_coverage_spec.rb`) before trusting
     # a `false` here as a real gap.
+    # @param name [String] a `CONSTRUCTS` key, such as `"Aggregate"`
+    # @param field [String, Symbol] the declared field to check propagation for
+    # @return [Hash{Symbol => Object}] `:name`, `:field`, and `:touchpoints` — an
+    #   `Array<Hash>` of `:touchpoint` (String) and `:present` (Boolean, or nil when the
+    #   touchpoint does not apply to `name`)
+    # @raise [ArgumentError] if `name` is not a `CONSTRUCTS` key
     def impact_preview(name, field)
       CONSTRUCTS.fetch(name) { raise ArgumentError, "no such construct #{name.inspect} — known: #{CONSTRUCTS.keys.join(', ')}" }
       field = field.to_s
@@ -402,6 +441,10 @@ module Hecks
     end
     private_class_method :rust_mentions?
 
+    # Renders one field's touchpoint checklist as text.
+    #
+    # @param preview [Hash] `impact_preview`'s own output
+    # @return [String] the human-readable rendering
     def format_impact_preview(preview)
       lines = ["== #{preview[:name]}##{preview[:field]} =="]
       preview[:touchpoints].each do |t|
@@ -421,6 +464,10 @@ module Hecks
       lines.join("\n")
     end
 
+    # Renders the duplicate-rule groups as text.
+    #
+    # @param groups [Array<Hash>] `duplicates`' own output
+    # @return [String] the human-readable rendering
     def format_duplicates(groups)
       return "no duplicate given/invariant/ensures rule found" if groups.empty?