hecks 1.4.0 → 1.5.0

data/lib/hecks/projector/docs_projector.rb

@@ -4,14 +4,16 @@ module Hecks
   module Projector
     # A bluebook, projected as its own usage documentation.
     #
-    # **What this is for**. A chapter in this corpus already contains everything a
-    # user of it needs: what each aggregate is (`description`), what each verb
-    # is for (`goal`) and who issues it (`role`), which states it moves
+    # ## What this is for
+    #
+    # A chapter in this corpus already contains everything a user of it
+    # needs: what each aggregate is (`description`), what each verb is
+    # for (`goal`) and who issues it (`role`), which states it moves
     # between, what it refuses and in whose words (`given`, `invariant`,
-    # `ensures`), and what each list is worth reading (`description` on a
-    # query). None of that reaches the person who has to call the domain.
-    # They read the source, or they read a document somebody wrote beside the
-    # source and stopped updating.
+    # `ensures`), and what each list is worth reading (`description` on
+    # a query). None of that reaches the person who has to call the
+    # domain. They read the source, or they read a document somebody
+    # wrote beside the source and stopped updating.
     #
     # `docs/implemented/reference/` is the precedent and the contrast. `bin/reference`
     # generates it from the language's own Syntax chapter, so the reference
@@ -19,12 +21,14 @@ module Hecks
     # down: the usage document for a domain, generated from that domain, so it
     # cannot drift from the domain either.
     #
-    # Why it is a projection and not a generator script. `Projector` is the
-    # repository's registry of "canonical IR in, external artifact out" (§30
-    # of the implementation plan), and this is exactly that shape: one
-    # bluebook's IR in, markdown out, no runtime needed and no store touched.
-    # Registered as `:docs` beside `:ir`, and reachable the way every
-    # projector is — `Projector.call(:docs, bluebook: ...)`.
+    # ## Why a projection, not a generator script
+    #
+    # `Projector` is the repository's registry of "canonical IR in,
+    # external artifact out" (§30 of the implementation plan), and this
+    # is exactly that shape: one bluebook's IR in, markdown out, no
+    # runtime needed and no store touched. Registered as `:docs` beside
+    # `:ir`, and reachable the way every projector is —
+    # `Projector.call(:docs, bluebook: ...)`.
     #
     # And as a method, which is the half that makes it get used.
     # `Facade::Surface` already installs a module per chapter carrying
@@ -33,17 +37,30 @@ module Hecks
     # `QualityControl::Bug.docs`. A document you have to remember a script for
     # is a document nobody reads.
     #
-    # **What it deliberately does not do**: invent. Every sentence below comes out
-    # of the chapter. Where a chapter says nothing — an aggregate with no
-    # `description`, a command with no `goal` — the document says nothing
-    # rather than filling the gap with a restatement of the name, because a
-    # generated paragraph that only rephrases an identifier teaches a reader
-    # to skim the ones that do not.
+    # ## What it deliberately does not do
+    #
+    # Invent. Every sentence below comes out of the chapter. Where a
+    # chapter says nothing — an aggregate with no `description`, a
+    # command with no `goal` — the document says nothing rather than
+    # filling the gap with a restatement of the name, because a
+    # generated paragraph that only rephrases an identifier teaches a
+    # reader to skim the ones that do not.
     module DocsProjector
       module_function
 
+      # Projects `bluebook` as its own usage documentation.
+      #
       # `options[:heading]` sets the top heading level (default 1), so a
       # caller splicing this into a larger document can push it down.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter 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
+      # @return [String] the document, as Markdown, 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]
@@ -60,6 +77,13 @@ module Hecks
       # matched no head returned "" and exit 0, which is the silent-wrong-
       # answer shape this repository has already been bitten by twice in the
       # query engine. A misspelling should cost a sentence, not a puzzle.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to look in
+      # @param only [String, Symbol, nil] narrows the result to the one aggregate
+      #   named; nil answers every aggregate
+      # @return [Array<Bluebook::Aggregate>, Bluebook::Aggregate] every declared
+      #   aggregate, or the single aggregate `only` names
+      # @raise [Runtime::NotFound] if `only` names no aggregate `bluebook` declares
       def aggregates(bluebook, only)
         return bluebook.aggregates unless only
 
@@ -69,10 +93,21 @@ module Hecks
                 "it declares #{bluebook.aggregates.map(&:hecks_name).sort.join(', ')}")
       end
 
+      # Renders a Markdown heading line.
+      #
+      # @param depth [Integer] the heading level
+      # @param text [String] the heading text
+      # @return [String] a Markdown `#`-prefixed heading line
       def h(depth, text) = "#{'#' * depth} #{text}"
 
       # ── the chapter ───────────────────────────────────────────────────
 
+      # Renders the chapter-level header: its title, vision, classification,
+      # former name, and aggregate list.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to document
+      # @param depth [Integer] the heading level for the chapter's own title
+      # @return [String] the header's Markdown source
       def chapter_header(bluebook, depth)
         out = [h(depth, bluebook.name), ""]
         # The vision first and as a quote. It is the one sentence in a chapter
@@ -86,6 +121,10 @@ module Hecks
         out.join("\n")
       end
 
+      # Builds a construct's own GitHub-style heading anchor.
+      #
+      # @param name [String, Symbol] the construct name to anchor
+      # @return [String] the construct's own GitHub-style heading anchor
       def anchor(name) = Naming.snake(name).tr("_", "-")
 
       # What happens without anybody asking — the part of a domain a caller
@@ -93,6 +132,11 @@ module Hecks
       # them. A policy means one dispatch causes another, sometimes into a
       # different domain entirely; a saga means a sequence is being driven on
       # their behalf and can end in more than one place.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to document
+      # @param depth [Integer] the heading level for the "Reactions"/saga sections
+      # @return [String, nil] the closing's Markdown source, or nil if `bluebook`
+      #   declares no policy and no process manager
       def closing(bluebook, depth)
         out = []
 
@@ -123,6 +167,12 @@ module Hecks
 
       # ── one aggregate ─────────────────────────────────────────────────
 
+      # Documents one aggregate: its description, identity, references,
+      # attributes, lifecycle, verbs, queries, and nested entities.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate to document
+      # @param depth [Integer] the heading level for the aggregate's own title
+      # @return [String] the aggregate's Markdown section
       def aggregate_section(aggregate, depth)
         out = [h(depth, aggregate.hecks_name), ""]
         out += [aggregate.description, ""] if aggregate.description
@@ -142,6 +192,12 @@ module Hecks
         out.compact.join("\n")
       end
 
+      # Documents one entity nested under `aggregate`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the entity's own owning aggregate
+      # @param entity [Bluebook::Entity] the entity to document
+      # @param depth [Integer] the heading level for the entity's own title
+      # @return [String] the entity's Markdown section
       def entity_section(aggregate, entity, depth)
         out = [h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})"), ""]
         out += [entity.description, ""] if entity.description
@@ -161,6 +217,12 @@ module Hecks
 
       # ── the shape ─────────────────────────────────────────────────────
 
+      # Renders a holder's own non-reference attributes as a Markdown table.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+      #   attributes to render
+      # @return [String, nil] the attribute/shape/rules table, or nil if `holder`
+      #   declares no non-reference attribute
       def attributes_table(holder)
         attributes = holder.attributes.reject(&:reference?)
         return nil if attributes.empty?
@@ -175,6 +237,11 @@ module Hecks
       # a caller nothing; `{ value: String }` tells them what to send, which is
       # the single most common thing to get wrong at this boundary — a bare
       # scalar where an object is wanted.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to describe
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `attribute`'s own holder
+      # @return [String] the attribute's shape: its value object's own fields, or its
+      #   scalar type, with "list of" and "*(optional)*" applied as declared
       def shape_of(attribute, holder)
         value_object = value_object_for(attribute, holder)
         inner =
@@ -187,6 +254,12 @@ module Hecks
         attribute.optional? ? "#{shape} *(optional)*" : shape
       end
 
+      # Lists an attribute's own rules: closed-set members, field patterns and
+      # defaults, invariants, and its own default.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to describe
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `attribute`'s own holder
+      # @return [String] the attribute's rules, joined with "; "; `""` if it has none
       def rules_of(attribute, holder)
         value_object = value_object_for(attribute, holder)
         rules = []
@@ -200,6 +273,11 @@ module Hecks
         rules.empty? ? "" : rules.join("; ")
       end
 
+      # Names a closed set's own members.
+      #
+      # @param value_object [Bluebook::ValueObject, nil] the value object to check
+      # @return [Array<Object>] every unique value across `value_object`'s own member
+      #   rows, or `[]` if `value_object` is nil or not a closed set
       def closed_members(value_object)
         return [] unless value_object&.closed_set?
 
@@ -208,6 +286,12 @@ module Hecks
 
       # An entity holds no value objects of its own — its argument types are
       # declared on the aggregate above it.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute whose type to resolve
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `attribute`'s own holder
+      # @return [Bluebook::ValueObject, nil] the value object class `attribute`'s type
+      #   names, found on `holder` or its own owning aggregate; nil if `attribute`'s
+      #   type is not a value object
       def value_object_for(attribute, holder)
         scopes = [holder, holder.respond_to?(:hecks_owner) ? holder.hecks_owner : nil].compact
         scopes.each do |scope|
@@ -221,6 +305,13 @@ module Hecks
 
       # ── the machine ───────────────────────────────────────────────────
 
+      # Renders a holder's own lifecycle as a "starting state" sentence and a
+      # verb/from/to table.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to document
+      # @param depth [Integer] the heading level for the "Lifecycle" section
+      # @return [String, nil] the section's Markdown source, or nil if `holder`
+      #   declares no lifecycle
       def lifecycle_section(holder, depth)
         lifecycle = holder.lifecycle or return nil
 
@@ -234,6 +325,13 @@ module Hecks
 
       # ── the verbs ─────────────────────────────────────────────────────
 
+      # Documents every command a holder declares.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+      #   commands to document
+      # @param depth [Integer] the heading level for the "Verbs" section
+      # @return [String, nil] the section's Markdown source, or nil if `holder`
+      #   declares no command
       def verbs_section(holder, depth)
         commands = holder.commands
         return nil if commands.empty?
@@ -243,6 +341,13 @@ module Hecks
         out.join("\n")
       end
 
+      # Documents one command: its goal, role, arguments, refusals,
+      # guarantees, and emitted events.
+      #
+      # @param command [Bluebook::Command] the command to document
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @param depth [Integer] the heading level for the command's own title
+      # @return [String] the command's Markdown section
       def command_entry(command, holder, depth)
         out = [h(depth, "#{command.hecks_name}#{' *(creates)*' if command.creates?}"), ""]
         out += [command.goal, ""] if command.goal
@@ -270,6 +375,11 @@ module Hecks
       # nothing to share with `command_entry`'s other sections, extracted
       # only to keep that method to the one shape every section there
       # follows: build a chunk, append it if non-empty.
+      #
+      # @param arguments [Array<Bluebook::Attribute>] the command's own arguments
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the arguments' own holder
+      # @return [Array<Array(String, String, String)>] one `[argument, shape, needed]`
+      #   row per argument
       def command_argument_rows(arguments, holder)
         arguments.map do |attribute|
           shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : shape_of(attribute, holder)
@@ -282,6 +392,10 @@ module Hecks
       # `given`s, and the fact that a reference has to resolve. A caller
       # reading only the argument list learns none of these, and they are
       # most of what a domain is.
+      #
+      # @param command [Bluebook::Command] the command to gather refusals for
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] `command`'s own holder
+      # @return [Array<String>] every way `command` can refuse, stated as sentences
       def refusals_of(command, holder)
         refusals = []
 
@@ -304,6 +418,12 @@ module Hecks
 
       # ── the reads ─────────────────────────────────────────────────────
 
+      # Renders a list of queries as one Markdown paragraph per query.
+      #
+      # @param queries [Array<Bluebook::Query>] the queries to document
+      # @param depth [Integer] the heading level for `title`
+      # @param title [String] the section's own heading text
+      # @return [String, nil] the section's Markdown source, or nil if `queries` is empty
       def queries_section(queries, depth, title)
         return nil if queries.empty?
 
@@ -320,6 +440,12 @@ module Hecks
         out.join("\n")
       end
 
+      # Renders a Markdown pipe table.
+      #
+      # @param headers [Array<String>] the column headers
+      # @param rows [Array<Array<String>>] each row's own cell values, matching
+      #   `headers`' width
+      # @return [String] the rendered table, ending in a blank line
       def table(headers, rows)
         lines = ["| #{headers.join(' | ')} |", "|#{headers.map { '---' }.join('|')}|"]
         rows.each { |row| lines << "| #{row.join(' | ')} |" }

data/lib/hecks/projector/exporter.rb

@@ -13,10 +13,18 @@ module Hecks
     module Exporter
       module_function
 
+      # Exports every booted bluebook's own canonical IR.
+      #
+      # @param registry [Runtime::Registry] the booted registry to export
+      # @return [Hash{String => Hash}] each domain name, mapped to its bluebook's `to_h`
       def call(registry)
         registry.bluebooks.transform_values(&:to_h)
       end
 
+      # Exports every booted bluebook's own canonical IR as JSON.
+      #
+      # @param registry [Runtime::Registry] the booted registry to export
+      # @return [String] `call`'s output, as pretty-printed JSON
       def json(registry)
         JSON.pretty_generate(call(registry))
       end
@@ -42,6 +50,12 @@ module Hecks
       # already answers for a domain with nothing lineage-capable bound —
       # `capable_aggregates: []` — rather than raising on an undefined
       # constant.
+      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+      # @param domain_name [String] the domain to check era-adapter lineage capability for
+      # @return [Hash{Symbol => Array<Hash{Symbol => String}>}] `:capable_aggregates`,
+      #   each a `:name`/`:storage_name` Hash; empty when the era plugin is unloaded or
+      #   nothing this domain binds is lineage-capable
+      # @raise [KeyError] if `domain_name` is not a loaded domain
       def lineage(registry, domain_name)
         return { capable_aggregates: [] } unless Ports::Persistence.plugin?(:era)
 
@@ -68,6 +82,13 @@ module Hecks
       # today), rather than silently building up a second, disjoint
       # history nothing but Rust ever reads while the real state stays
       # wherever its own adapter actually wrote it.
+      # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+      # @param domain_name [String] the domain to export persistence bindings for
+      # @return [Hash{Symbol => Array<Hash{Symbol => Object}>}] `:aggregates`, each a
+      #   `:name`/`:storage_name`/`:adapter` Hash
+      # @raise [KeyError] if `domain_name` is not a loaded domain
+      # @raise [Runtime::WiringError] if an aggregate has no authoritative bind, more
+      #   than one, or a bind with a role this port does not support
       def persistence(registry, domain_name)
         bluebook = registry.bluebooks.fetch(domain_name)
         aggregates = bluebook.aggregates.map do |aggregate|
@@ -85,6 +106,12 @@ module Hecks
       # "authorization"`), with that chapter's declared verbs qualified.
       # `rust/host` (auth.rs) reads this instead of naming Governance.
       # `{}` when nothing this domain attaches provides authorization.
+      # @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
+      #   authorization
       def authorization(registry, domain_name)
         provider = registry.authorization_provider_for(domain_name)
         return {} unless provider
@@ -107,10 +134,19 @@ module Hecks
       # separate). `values:` tables serialize as `[key, value]` pairs,
       # never an object, because JSON object keys are always strings and
       # a convert's keys are typed.
+      # @param registry [Runtime::Registry] the booted registry to export translations from
+      # @return [Array<Hash>] every registered translation, as `compiled_translation_hash`
+      #   builds
       def translations(registry)
         registry.translations.map { |translation| compiled_translation_hash(translation) }
       end
 
+      # Exports one translation, its aggregates' compiled SQL included.
+      #
+      # @param translation [Bluebook::Translation] the translation to export
+      # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
+      #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
+      #   (each `compiled_translation_aggregate`'s own Hash)
       def compiled_translation_hash(translation)
         {
           domain:     translation.domain,
@@ -121,6 +157,10 @@ module Hecks
         }
       end
 
+      # Exports every registered translation as JSON.
+      #
+      # @param registry [Runtime::Registry] the booted registry to export translations from
+      # @return [String] `translations`' output, as pretty-printed JSON
       def translations_json(registry)
         JSON.pretty_generate(translations(registry))
       end
@@ -136,6 +176,10 @@ module Hecks
       # reviewed never changed at all. The approval binds to what was
       # declared, not to what a particular compiler build happened to
       # emit from it.
+      # @param translation [Bluebook::Translation] the translation to digest
+      # @return [Hash{Symbol => Object}] `:domain` (String), `:from`/`:to` (the era
+      #   identifiers as declared), `:retired` (`Array<String>`), and `:aggregates`
+      #   (each `translation_aggregate`'s own Hash)
       def translation_hash(translation)
         {
           domain:     translation.domain,
@@ -146,6 +190,14 @@ module Hecks
         }
       end
 
+      # Digests one aggregate's own declared translation rules.
+      #
+      # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
+      #   translation rules to digest
+      # @return [Hash{Symbol => Object}] `:name` (String), `:was` (String, nil),
+      #   `:renames` (`Hash{String => String}`), `:moves`/`:converts`/`:retypes`/
+      #   `:computes`/`:rekeys`/`:backfills` (each an `Array<Hash>`), `:drops`
+      #   (`Array<String>`)
       def translation_aggregate(aggregate)
         {
           name:      aggregate.name,
@@ -158,17 +210,14 @@ module Hecks
           drops:     aggregate.drops.map(&:to_s),
           retypes:   aggregate.retypes.map { |retype| { from: retype.from, to: retype.to } },
           computes:  aggregate.computes.map { |compute| { from: compute.from, to: compute.to, sql: compute.sql } },
-          # **Previously missing** — found live while planning Rust-side mint
-          # support. An edge carrying only a rekey (no compute) had its
-          # approval bind to nothing rekey-specific at all: any two
-          # rekey edges with otherwise-identical renames/moves/converts/
-          # drops/retypes/computes produced the same digest regardless
-          # of what their `rekey sql:` actually said, and a rekey's own
-          # SQL could change without invalidating an existing approval.
-          # Same bug shape for `backfills` (present, just never
-          # exported). Fixing this changes every existing rekey/
-          # backfill edge's digest — any approval already recorded for
-          # one is invalidated by this fix and must be re-reviewed.
+          # **`rekeys`/`backfills` are digest-relevant too.** Without them, an
+          # edge carrying only a rekey (no compute) would bind its approval
+          # to nothing rekey-specific: any two rekey edges with otherwise-
+          # identical renames/moves/converts/drops/retypes/computes would
+          # produce the same digest regardless of what their `rekey sql:`
+          # actually said, letting a rekey's own SQL change without
+          # invalidating an existing approval. Same reasoning covers
+          # `backfills`.
           rekeys:    aggregate.rekeys.map { |rekey| { sql: rekey.sql } },
           backfills: aggregate.backfills.map { |backfill| { name: backfill.name.to_s, default: backfill.default } }
         }
@@ -197,6 +246,11 @@ module Hecks
       # declared-rules shape, just without precompiled SQL to execute —
       # consistent with there being no mint/audit machinery to run it
       # against either.
+      # @param aggregate [Bluebook::TranslationAggregate] the aggregate's own
+      #   translation rules to compile and export
+      # @return [Hash{Symbol => Object}] `translation_aggregate`'s own Hash, plus
+      #   `:compiled_state_expression` (String) and `:compiled_id_expression`
+      #   (String, nil) when the era persistence plugin is loaded
       def compiled_translation_aggregate(aggregate)
         return translation_aggregate(aggregate) unless Ports::Persistence.plugin?(:era)
 

data/lib/hecks/projector/ir_projector.rb

@@ -12,6 +12,12 @@ module Hecks
     module IRProjector
       module_function
 
+      # Projects `bluebook` as its own canonical IR.
+      #
+      # @param bluebook [Hecks::IR] the IR-emitting construct to project
+      # @param options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [Hash] `bluebook`'s canonical IR, as built by `Hecks::IR::Emits#to_h`
+      # @raise [Hecks::IR::Undeclared] if `bluebook` never declared its shape with `emits_ir`
       def call(bluebook:, options: {}) = bluebook.to_h
     end
   end