hecks 1.4.0 → 1.5.0

data/lib/hecks/projections/diagrams.rb

@@ -2,14 +2,16 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # A domain's own shape, projected as MERMAID diagrams — the same
+    # A domain's own shape, projected as Mermaid diagrams — the same
     # trick `Projections::Reference`/`DocsProjector` already play for
     # prose, one level further: a diagram generated from the
     # declaration can't drift from it the way a hand-drawn one
     # inevitably does, because there is no second copy to forget to
     # update.
     #
-    # MERMAID, not Graphviz (the two considered) — every diagram type
+    # ## Why Mermaid, not Graphviz
+    #
+    # Mermaid, not Graphviz (the two considered) — every diagram type
     # below has a Mermaid form purpose-built for exactly what the
     # underlying construct already is (a `lifecycle` is a state
     # machine, `has_many`/`belongs_to` already speaks in cardinality,
@@ -23,6 +25,8 @@ module Hecks
     # dependency earns its way past std") would rather not take just to
     # draw a diagram.
     #
+    # ## Diagram kinds
+    #
     # Four diagram kinds, one file each per domain except lifecycles
     # (one per lifecycle-bearing construct, since that's how a reader
     # actually reaches for it — looking at one aggregate's states, not
@@ -62,6 +66,8 @@ module Hecks
     #                                          here that looks outward past
     #                                          this domain's own boundary
     #
+    # ## Node and construct naming
+    #
     # Construct names (aggregate/entity/command/event) are used bare,
     # unsanitized, as Mermaid node/entity ids — safe because this
     # language's own word grammar only ever admits simple CamelCase/
@@ -79,6 +85,14 @@ module Hecks
 
       module_function
 
+      # Projects one domain's whole shape into every diagram kind it has data
+      # for, one Mermaid file per entry.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter to project
+      # @param options [Hash{Symbol => Object}] projection options; only `:hecksagon`
+      #   (a `Bluebook::Hecksagon`, or `nil`) is read, and only by `frameworks_diagram`
+      # @return [Hash{String => String}] each diagram's filename (such as
+      #   `"relationships.mmd"`) mapped to its rendered Mermaid source
       def call(bluebook:, options: {})
         files = {}
 
@@ -125,18 +139,35 @@ module Hecks
 
       # ── shared ────────────────────────────────────────────────────────
 
+      # Every aggregate and entity in this domain, flattened into one list —
+      # everything a lifecycle/relationship/command diagram walks alike.
+      #
       # An entity can carry its own lifecycle, relationship, or command
       # too — its own `lifecycle`/`reference_to`/`command` block,
       # addressed through its holding aggregate the same way
       # `DocsProjector` already treats an aggregate and its entities
       # alike. Walking both here means a domain's entity gaining any of
       # these needs no change to this file.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to walk
+      # @return [Array<Bluebook::Aggregate, Class>] every aggregate, and every entity
+      #   class (a `Bluebook::Entity` subclass) nested under it, in declaration order
       def holders(bluebook)
         bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
       end
 
+      # The holders (see `holders`) that declare their own `lifecycle` block —
+      # one diagram file is projected per lifecycle-bearing holder, not one
+      # per domain.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to walk
+      # @return [Array<Bluebook::Aggregate, Class>] every holder with a non-nil
+      #   `lifecycle`
       def holders_with_lifecycle(bluebook) = holders(bluebook).select(&:lifecycle)
 
+      # Renders the two-line `%%` comment banner every generated diagram file
+      # opens with, warning against hand edits and naming how to regenerate it.
+      #
       # `chapter_name` drives the re-run hint always — that's the one
       # argument `bin/project_diagrams` actually takes, regardless of
       # which single aggregate/entity `subject` happens to name. Passing
@@ -144,6 +175,10 @@ module Hecks
       # `Order_lifecycle.mmd` telling a reader to run
       # `bin/project_diagrams <domain-path> Order` — a chapter name
       # Hecks.boot has never heard of.
+      #
+      # @param chapter_name [String] the domain's chapter name, used in the re-run hint
+      # @param subject [String] prose naming what this specific file was generated from
+      # @return [String] the two-line `%%`-commented Mermaid banner, newline-terminated
       def header(chapter_name, subject)
         <<~HEADER
           %% GENERATED by bin/project_diagrams from #{subject} — DO NOT EDIT BY HAND.
@@ -153,6 +188,15 @@ module Hecks
 
       # ── lifecycle -> stateDiagram-v2 ─────────────────────────────────
 
+      # Renders one holder's own declared `lifecycle` as a Mermaid
+      # `stateDiagram-v2` — its default starting state, and one edge per
+      # transition, labeled by the command that causes it.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter `holder` belongs to, for the
+      #   file's re-run banner
+      # @param holder [Bluebook::Aggregate, Class] the aggregate or entity class (a
+      #   `Bluebook::Entity` subclass) whose `lifecycle` to draw
+      # @return [String] the rendered Mermaid `stateDiagram-v2` source
       def lifecycle_diagram(bluebook, holder)
         lifecycle = holder.lifecycle
         edges = lifecycle.transitions.flat_map do |command_name, transition|
@@ -169,6 +213,10 @@ module Hecks
 
       # ── relationships -> erDiagram ───────────────────────────────────
 
+      # Renders the whole domain's declared `has_many`/`has_one`/`belongs_to`/
+      # `reference_to` attributes as a Mermaid `erDiagram`, one edge per
+      # reference attribute across every holder.
+      #
       # Standard crow's-foot reading, the same convention every ORM's own
       # ERD generator (Rails' erd gem included) already uses:
       # `has_many`/`has_one` are read from the owning side — one Holder
@@ -181,6 +229,10 @@ module Hecks
       # absent (a nilable reference, an empty has_one) — never the
       # crow's-foot "many" marker, which is a structural fact independent
       # of any one instance's optionality.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @return [String, nil] the rendered Mermaid `erDiagram` source, or `nil` if the
+      #   domain declares no reference attribute at all
       def relationship_diagram(bluebook)
         edges = holders(bluebook).flat_map do |holder|
           holder.attributes.select(&:reference?).map { |attribute| relationship_edge(holder, attribute) }
@@ -191,6 +243,14 @@ module Hecks
         "#{header(bluebook.name, subject)}erDiagram\n#{edges.join("\n")}\n"
       end
 
+      # One erDiagram edge for one holder's own declared reference attribute,
+      # in the DSL word's own crow's-foot reading (see `relationship_diagram`).
+      #
+      # @param holder [Bluebook::Aggregate, Class] the aggregate or entity class (a
+      #   `Bluebook::Entity` subclass) that declares `attribute`
+      # @param attribute [Bluebook::Attribute] a reference attribute (`attribute.reference?`
+      #   is true); its `relationship` names which DSL word minted it
+      # @return [String] the rendered `erDiagram` edge line
       def relationship_edge(holder, attribute)
         target = attribute.type.target_name
         case attribute.relationship
@@ -213,6 +273,10 @@ module Hecks
       # aggregates may share a command name; event ids are bare
       # (`evt_PizzaCreated`) since an event is this domain's own
       # addressing key, the same way `policy.on_event` reaches it.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @return [String, nil] the rendered Mermaid flowchart source, or `nil` if the
+      #   domain declares no command `emits` and no policy at all
       def dispatch_diagram(bluebook)
         lines = []
 
@@ -231,6 +295,14 @@ module Hecks
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
       end
 
+      # One flowchart edge from a command to one event it declares it `emits`.
+      #
+      # @param holder [Bluebook::Aggregate, Class] the aggregate or entity class (a
+      #   `Bluebook::Entity` subclass) that declares `command`
+      # @param command [Class] the command class (a `Bluebook::Command` subclass) that
+      #   emits `event`
+      # @param event [String] the emitted event's name
+      # @return [String] the rendered `-->|emits|` edge line
       def emits_edge(holder, command, event)
         %(    #{command_node(holder.hecks_name, command.hecks_name)} -->|emits| #{event_node(event)})
       end
@@ -246,6 +318,10 @@ module Hecks
       # edge of its own here, which honestly shows "dispatch continues
       # elsewhere" rather than silently dropping the edge. The label
       # names which domain, so that's not a dead end on the page either.
+      #
+      # @param policy [Bluebook::Policy] the policy to draw as a trigger edge
+      # @return [String] the rendered `-->|triggers|` (or `-->|triggers in <domain>|`)
+      #   edge line
       def trigger_edge(policy)
         bare_event = policy.on_event.to_s.split(".").last
         aggregate_name, command_name = policy.trigger_command.to_s.split(".", 2)
@@ -253,14 +329,28 @@ module Hecks
         %(    #{event_node(bare_event)} -->|#{label}| #{command_node(aggregate_name, command_name)})
       end
 
+      # Mermaid stadium-shaped node id and label for one command, qualified by
+      # its owning aggregate since two aggregates may share a command name.
+      #
+      # @param aggregate_name [String] the command's owning aggregate/entity name
+      # @param command_name [String] the command's own name
+      # @return [String] the rendered `cmd_<aggregate>_<command>(["..."])` node
       def command_node(aggregate_name, command_name)
         %(cmd_#{aggregate_name}_#{command_name}(["#{aggregate_name}.#{command_name}"]))
       end
 
+      # Mermaid hexagonal node id and label for one event, addressed bare since
+      # an event is this domain's own addressing key.
+      #
+      # @param event_name [String] the event's own name
+      # @return [String] the rendered `evt_<event>{{"..."}}` node
       def event_node(event_name) = %(evt_#{event_name}{{"#{event_name}"}})
 
       # ── roles -> flowchart ────────────────────────────────────────────
 
+      # Renders every command's declared `role` as a Mermaid flowchart, one
+      # edge per role issuing a command.
+      #
       # Who issues what, across the whole domain — data no existing
       # projection draws at all today (the reference pages' own
       # `command_entry` only ever prints a command's role as a single
@@ -268,6 +358,10 @@ module Hecks
       # no declared `role` draws nothing — there is no fact to state.
       # Circle-shaped so a role reads as "who" beside `dispatch.mmd`'s
       # stadium ("what someone does") and hexagon ("what happened").
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @return [String, nil] the rendered Mermaid flowchart source, or `nil` if no
+      #   command in the domain declares a `role`
       def roles_diagram(bluebook)
         lines = holders(bluebook).flat_map do |holder|
           holder.commands.select(&:role).map { |command| role_edge(holder, command) }
@@ -278,17 +372,36 @@ module Hecks
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
       end
 
+      # One flowchart edge from a command's declared role to the command
+      # itself.
+      #
+      # @param holder [Bluebook::Aggregate, Class] the aggregate or entity class (a
+      #   `Bluebook::Entity` subclass) that declares `command`
+      # @param command [Class] the command class (a `Bluebook::Command` subclass); its
+      #   `role` is drawn
+      # @return [String] the rendered `-->|issues|` edge line
       def role_edge(holder, command)
         %(    #{role_node(command.role)} -->|issues| #{command_node(holder.hecks_name, command.hecks_name)})
       end
 
+      # Mermaid circular node id and label for one role, keeping the real
+      # free-text role string as the displayed label (see `role_id`).
+      #
+      # @param role_name [String] the command's declared `role` text
+      # @return [String] the rendered `role_<id>((<role>))` node
       def role_node(role_name) = %(#{role_id(role_name)}((#{role_name})))
 
+      # Sanitizes a free-text role name into a legal Mermaid node id.
+      #
       # A role name is free text ("Back office", "Vault officer") —
       # unlike every other name this file uses as a bare id, this one
       # has to be sanitized to become a legal Mermaid identifier. The
       # real string still appears as the node's own label
       # (`role_node`); only the id is mangled.
+      #
+      # @param role_name [String] the command's declared `role` text
+      # @return [String] `role_` followed by `role_name` with every run of
+      #   non-alphanumeric characters collapsed to a single underscore
       def role_id(role_name) = "role_#{role_name.to_s.gsub(/[^A-Za-z0-9]+/, '_')}"
 
       # ── ports -> flowchart ───────────────────────────────────────────
@@ -306,8 +419,8 @@ module Hecks
       # aggregate the port hangs off (always present — a port always
       # belongs to exactly one aggregate), and a solid "to:" edge to
       # whichever aggregate the operation itself names as its receiver
-      # (present only when `to:` is declared — PR #351's own real
-      # addition; before it, this data didn't exist to draw at all).
+      # (present only when `to:` is declared — an operation with no
+      # declared target has no destination of its own to draw).
       # `emits` reuses `dispatch.mmd`'s own `event_node` unchanged — the
       # same fact, reached from a different direction.
       #
@@ -317,6 +430,10 @@ module Hecks
       # it raises, it isn't just always empty), so walking entities here
       # the way every other diagram in this file does would crash on
       # the first entity-bearing domain.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @return [String, nil] the rendered Mermaid flowchart source, or `nil` if the
+      #   domain declares no port operation at all
       def ports_diagram(bluebook)
         lines = bluebook.aggregates.flat_map do |holder|
           holder.ports.flat_map { |port| port.operations.map { |operation| port_edges(holder, port, operation) } }
@@ -328,6 +445,14 @@ module Hecks
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
       end
 
+      # All of one port operation's own edges: the aggregate that exposes it,
+      # its optional `to:` routing target, and one edge per event it `emits`.
+      #
+      # @param holder [Bluebook::Aggregate] the aggregate `port` is attached to
+      # @param port [Bluebook::DomainPort] the port `operation` belongs to
+      # @param operation [Bluebook::PortOperation] the operation to draw
+      # @return [Array<String>] the rendered edge lines: one "exposes" edge, plus a
+      #   "to:" edge when `operation.to` is declared, plus one "emits" edge per event
       def port_edges(holder, port, operation)
         op = port_operation_node(holder.hecks_name, port.name, operation.hecks_name)
         edges = ["    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|exposes| #{op}"]
@@ -336,6 +461,13 @@ module Hecks
         edges
       end
 
+      # Mermaid trapezoidal node id and label for one port operation, qualified
+      # by both its owning aggregate and its owning port.
+      #
+      # @param aggregate_name [String] the operation's owning aggregate name
+      # @param port_name [String] the operation's owning port name
+      # @param operation_name [String] the operation's own name
+      # @return [String] the rendered `op_<aggregate>_<port>_<operation>[/"..."/]` node
       def port_operation_node(aggregate_name, port_name, operation_name)
         id = "op_#{aggregate_name}_#{port_name}_#{operation_name}"
         %(#{id}[/"#{port_name}.#{operation_name}"/])
@@ -343,6 +475,9 @@ module Hecks
 
       # ── read models -> flowchart ─────────────────────────────────────
 
+      # Renders the whole domain's declared `read_models` as a Mermaid
+      # flowchart, one edge per aggregate a read model is assembled from.
+      #
       # The read-side complement to `relationships.mmd` — that diagram
       # shows how aggregates reference each other for writes
       # (`has_many`/`belongs_to`/`reference_to`); this shows how a
@@ -369,6 +504,10 @@ module Hecks
       # read_model. Still MVP scope: `where`/`group_by`/`order_by`
       # aren't drawn at all yet — real facts, not invented, just not
       # this diagram's job yet.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @return [String, nil] the rendered Mermaid flowchart source, or `nil` if the
+      #   domain declares no `read_model` at all
       def read_model_diagram(bluebook)
         lines = bluebook.read_models.flat_map { |read_model| read_model_edges(read_model) }
         return nil if lines.empty?
@@ -377,6 +516,12 @@ module Hecks
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
       end
 
+      # One edge per aggregate one read model is assembled from, into that
+      # read model's own subroutine-shaped node.
+      #
+      # @param read_model [Bluebook::ReadModel] the read model to draw
+      # @return [Array<String>] the rendered edge lines, one per entry in
+      #   `read_model.to_h[:aggregate_heads]`
       def read_model_edges(read_model)
         shape = read_model.to_h
         node = %(rm_#{shape[:name]}[["#{read_model_label(shape)}"]])
@@ -394,6 +539,13 @@ module Hecks
         end
       end
 
+      # The read model's own subroutine node label — its name, with
+      # `(count)`/`(median: field)` appended for the two aggregations this
+      # diagram states.
+      #
+      # @param shape [Hash{Symbol => Object}] a `Bluebook::ReadModel#to_h` result;
+      #   reads `:name`, `:count` and `:median_field`
+      # @return [String] the node's display label
       def read_model_label(shape)
         return "#{shape[:name]} (count)" if shape[:count]
         return "#{shape[:name]} (median: #{shape[:median_field]})" if shape[:median_field]
@@ -403,6 +555,9 @@ module Hecks
 
       # ── surface -> flowchart ─────────────────────────────────────────
 
+      # Renders one holder's own commands (and what each writes) and queries
+      # as a Mermaid flowchart.
+      #
       # "What can I do to this, what can I ask about it" — one file per
       # holder, unlike every other diagram here: `dispatch.mmd` already
       # shows a command's own onward reaction chain, but never an
@@ -447,6 +602,12 @@ module Hecks
       # every other fact in this file. `append`'s own fields carry no
       # single source at all — its own field names are the fact worth
       # stating (real: `Order.AddTopping` appends `name, amount`).
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter `holder` belongs to, for the
+      #   file's re-run banner
+      # @param holder [Bluebook::Aggregate, Class] the aggregate or entity class (a
+      #   `Bluebook::Entity` subclass) whose commands and queries to draw
+      # @return [String] the rendered Mermaid flowchart source
       def surface_diagram(bluebook, holder)
         lines = holder.commands.map do |command|
           "    #{holder.hecks_name}[(#{holder.hecks_name})] -->|does| #{command_node(holder.hecks_name, command.hecks_name)}"
@@ -464,10 +625,25 @@ module Hecks
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
       end
 
+      # Mermaid diamond-shaped node id and label for one query, qualified by
+      # its owning aggregate.
+      #
+      # @param aggregate_name [String] the query's owning aggregate/entity name
+      # @param query_name [String] the query's own name
+      # @return [String] the rendered `qry_<aggregate>_<query>{"..."}` node
       def query_node(aggregate_name, query_name)
         %(qry_#{aggregate_name}_#{query_name}{"#{aggregate_name}.#{query_name}"})
       end
 
+      # One flowchart edge from a command to one attribute it mutates,
+      # labeled with what the mutation writes (see `mutation_label`).
+      #
+      # @param holder [Bluebook::Aggregate, Class] the aggregate or entity class (a
+      #   `Bluebook::Entity` subclass) that declares `command` and the mutated attribute
+      # @param command [Class] the command class (a `Bluebook::Command` subclass) that
+      #   declares `mutation`
+      # @param mutation [Bluebook::Mutation] the mutation to draw
+      # @return [String] the rendered `-->|"..."|` edge line
       def mutation_edge(holder, command, mutation)
         shape = mutation.to_h
         label = mutation_label(shape)
@@ -475,6 +651,13 @@ module Hecks
         %(    #{command_node(holder.hecks_name, command.hecks_name)} -->|"#{label}"| #{target})
       end
 
+      # The edge label naming what one mutation writes — the op, and either
+      # its bound field names (an append/delegate/corrects) or its value
+      # source (see `mutation_source_detail`).
+      #
+      # @param shape [Hash{Symbol => Object}] a `Bluebook::Mutation#to_h` result;
+      #   reads `:op`, and either `:fields` or `:source`
+      # @return [String] the rendered `"<op>s: <detail>"` label text
       def mutation_label(shape)
         verb = "#{shape[:op]}s"
         # `fields:` (not `source:`) is the multi-binding shape
@@ -501,14 +684,27 @@ module Hecks
       # was caught). Swapped for a single quote here rather than
       # escaped, the same "state it, don't invent it, just make it
       # legal Mermaid" trade `read_models.mmd`'s own quoting fix made.
+      #
+      # @param source [Hash{Symbol => Object}] a classified mutation source: `{kind:
+      #   "literal", value:}`, `{kind: "argument", name:}`, or `{kind: "state", name:}`
+      # @return [String] `source[:value]` quoted for a literal, `source[:name]` for an
+      #   argument, or `source[:kind]` itself for any other kind
       def mutation_source_detail(source)
         case source[:kind]
         when "literal"  then "'#{source[:value].to_s.tr('"', "'")}'"
         when "argument" then source[:name]
-        else source[:kind] # a source kind this file has no real corpus example of yet — named, not hidden
+        else
+          # A source kind this file has no real corpus example of yet — named, not hidden.
+          source[:kind]
         end
       end
 
+      # Mermaid plain-rectangle node id and label for one attribute a
+      # mutation writes, qualified by its owning holder.
+      #
+      # @param holder_name [String] the attribute's owning aggregate/entity name
+      # @param attribute_name [Symbol, String] the mutated attribute's own name
+      # @return [String] the rendered `attr_<holder>_<attribute>[<attribute>]` node
       def attribute_node(holder_name, attribute_name)
         %(attr_#{holder_name}_#{attribute_name}[#{attribute_name}])
       end
@@ -544,6 +740,12 @@ module Hecks
       # dispatch declined is exactly as real a cause of a state
       # transition as an event announced, and the diagram states it
       # exactly as verbatim as every other edge here does.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter `saga` belongs to, for the
+      #   file's re-run banner
+      # @param saga [Bluebook::ProcessManager] the process manager whose states and
+      #   dispatches to draw
+      # @return [String] the rendered Mermaid `stateDiagram-v2` source
       def saga_diagram(bluebook, saga)
         edges = saga.handlers.map { |handler| saga_edge(handler, saga) }
 
@@ -556,7 +758,10 @@ module Hecks
         MERMAID
       end
 
-      # The REFUSED edge's own dispatch list is partly derived now —
+      # One stateDiagram-v2 edge for one saga handler, labeled by the event
+      # that causes it and what it dispatches.
+      #
+      # The `REFUSED` edge's own dispatch list is partly derived now —
       # per-dispatch saga compensation (`compensates`) moved a saga's own
       # compensating dispatches off the hand-written `on :refused` leg
       # and onto whichever forward dispatch each one undoes, so
@@ -564,9 +769,15 @@ module Hecks
       # edge for any saga using it — accurate to the declaration, wrong
       # about what the runtime actually does at refusal (it derives and
       # fires every declared `compensates`, newest first). `saga` is
-      # passed through for exactly this — only the REFUSED handler needs
+      # passed through for exactly this — only the `REFUSED` handler needs
       # it, every other edge's own `handler.dispatches` already says
       # everything real about it.
+      #
+      # @param handler [Bluebook::ProcessManagerHandler] the handler row to draw as
+      #   an edge
+      # @param saga [Bluebook::ProcessManager] the process manager `handler` belongs
+      #   to, needed only to derive the `REFUSED` edge's compensating dispatches
+      # @return [String] the rendered `-->` stateDiagram-v2 edge line
       def saga_edge(handler, saga)
         label = handler.event_type
         # Derived first, then the hand-written body — the same order
@@ -585,12 +796,20 @@ module Hecks
       # derives and fires (newest-first, at actual refusal time; this
       # diagram states them in declaration order, since it draws the
       # saga's own shape, not one instance's own runtime history).
+      #
+      # @param saga [Bluebook::ProcessManager] the process manager whose declared
+      #   compensations to list
+      # @return [Array<String>] the name of each compensating command declared anywhere
+      #   in `saga`, in declaration order
       def derived_compensations(saga)
         saga.handlers.flat_map { |handler| handler.dispatches.filter_map { |dispatch| dispatch.compensates&.command_name } }
       end
 
       # ── frameworks -> flowchart ─────────────────────────────────────
 
+      # Renders the whole domain's declared `uses_framework` attachments and
+      # cross-domain policy targets as a Mermaid flowchart.
+      #
       # Every other diagram in this file stays inside one domain's own
       # boundary — this is the one that steps outside it. A real domain
       # depends on another domain's own aggregates in exactly two ways:
@@ -629,6 +848,13 @@ module Hecks
       # caller, or a spec that doesn't care) just means no frameworks.mmd
       # — same "nothing to state" skip every other diagram here already
       # takes when its own underlying data is empty.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter to project
+      # @param hecksagon [Bluebook::Hecksagon, nil] the chapter's `.hecksagon`, holding
+      #   its `framework_members`, or `nil` if the caller has none to hand in
+      # @return [String, nil] the rendered Mermaid flowchart source, or `nil` if
+      #   `hecksagon` is `nil`, or the domain declares no `uses_framework` and no
+      #   cross-domain policy target
       def frameworks_diagram(bluebook, hecksagon)
         return nil unless hecksagon
 
@@ -641,6 +867,16 @@ module Hecks
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
       end
 
+      # One flowchart edge from this domain to a dependency, dotted for a
+      # standing `attaches` and solid for a `reaches across` that only fires
+      # when a policy does.
+      #
+      # @param from [String] this domain's own name
+      # @param label [String] the edge label, `"attaches"` or `"reaches across"`
+      # @param to [String, Symbol] the dependency domain's name
+      # @param dotted [Boolean] whether to render a dotted (`true`) or solid (`false`)
+      #   arrow
+      # @return [String] the rendered edge line
       def domain_edge(from, label, to, dotted:)
         arrow = dotted ? "-.->" : "-->"
         %(    #{from}[(#{from})] #{arrow}|#{label}| #{to}[(#{to})])