hecks 1.3.0 → 1.5.0

data/lib/hecks/projections/glossary/html.rb

@@ -3,14 +3,14 @@ require_relative "../../forms/html"
 module Hecks
   module Projections
     module Glossary
-      # THE PAGE, RENDERED FROM THE MARKDOWN — `html/index.html` is
+      # **The page, rendered from the markdown** — `html/index.html` is
       # `glossary.md` read back and dressed: a navigation rail built from
       # its `##` headings, each `###` a term entry, every ```mermaid fence
       # a diagram, every `[x](#y)` an in-page link. Nothing here reads
       # the bluebook; if the page shows it, the Markdown says it, so the
       # two cannot drift.
       #
-      # A SUBSET RENDERER, NOT A MARKDOWN LIBRARY — the projector emits
+      # A subset renderer, not a markdown library — the projector emits
       # a fixed handful of constructs (`Markdown`'s own header lists
       # them), and this reads exactly those. The Gemfile keeps every
       # dependency justified in its own comment; a full Markdown engine
@@ -30,6 +30,10 @@ module Hecks
 
         module_function
 
+        # Renders `glossary.md`'s Markdown source as a self-contained HTML page.
+        #
+        # @param markdown [String] `glossary.md`'s own rendered Markdown source
+        # @return [String] the complete `html/index.html` source
         def render(markdown)
           blocks = parse(markdown)
           slugs  = heading_slugs(blocks)
@@ -40,6 +44,12 @@ module Hecks
 
         # ── reading the Markdown ─────────────────────────────────────────
 
+        # Parses the subset of Markdown the glossary projector emits into
+        # structured blocks.
+        #
+        # @param markdown [String] the Markdown source to parse
+        # @return [Array<Block>] one block per heading, quote, list, mermaid
+        #   fence, or paragraph, in document order
         def parse(markdown)
           lines  = markdown.lines.map(&:chomp)
           blocks = []
@@ -70,6 +80,11 @@ module Hecks
 
         # The mermaid source between the opening fence at `index` and its
         # closing one, and the index just past that.
+        #
+        # @param lines [Array<String>] the document's lines
+        # @param index [Integer] the opening ` ```mermaid ` fence's line index
+        # @return [Array(Block, Integer)] the parsed `:mermaid` block, and the line
+        #   index just past its closing fence
         def fence(lines, index)
           close = ((index + 1)...lines.size).find { |at| lines[at] == "```" } || lines.size
           [Block.new(type: :mermaid, text: lines[(index + 1)...close].join("\n")), close + 1]
@@ -77,6 +92,13 @@ module Hecks
 
         # The consecutive lines from `index` that satisfy the block, and
         # the index just past them.
+        #
+        # @param lines [Array<String>] the document's lines
+        # @param index [Integer] the line index to start scanning from
+        # @yieldparam text [String] one candidate line
+        # @yieldreturn [Boolean] whether that line belongs to the run
+        # @return [Array(Array<String>, Integer)] the consecutive matching lines, and
+        #   the line index just past them
         def run(lines, index)
           taken = []
           while index < lines.size && yield(lines[index])
@@ -89,10 +111,14 @@ module Hecks
         # The same slugs GitHub would give these headings, in the same
         # order — so the links the Markdown carries land here too.
         #
-        # KEYED BY THE BLOCK ITSELF, NOT ITS VALUE — a Struct compares by
+        # Keyed by the block itself, not its value — a Struct compares by
         # members, so two "### Open" headings in different sections would
         # otherwise be one key, and the first would answer with the
         # second's "-1" slug, leaving `#open` with nothing to land on.
+        #
+        # @param blocks [Array<Block>] every parsed block, in document order
+        # @return [Hash{Block => String}] each heading block, mapped to its GitHub-style
+        #   slug, keyed by object identity
         def heading_slugs(blocks)
           seen  = Hash.new(0)
           slugs = {}.compare_by_identity
@@ -106,6 +132,11 @@ module Hecks
 
         # Everything before the first `##` is the front matter; each `##`
         # opens a section that runs to the next.
+        #
+        # @param blocks [Array<Block>] every parsed block, in document order
+        # @return [Array<Hash{Symbol => Object}>] one Hash per section: `:heading`
+        #   (the `Block`, or nil for the leading front matter) and `:blocks` (its
+        #   own `Array<Block>`)
         def split_sections(blocks)
           sections = [{ heading: nil, blocks: [] }]
           blocks.each do |block|
@@ -117,6 +148,13 @@ module Hecks
 
         # ── writing the page ─────────────────────────────────────────────
 
+        # Renders the full HTML page shell around the navigation rail and content.
+        #
+        # @param title [String] the document's `#` heading text
+        # @param sections [Array<Hash{Symbol => Object}>] every `##` section, as
+        #   `split_sections` builds (the front matter excluded by the caller)
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [String] the complete HTML page source
         def page(title, sections, slugs)
           front, *rest = sections
           <<~HTML
@@ -148,6 +186,14 @@ module Hecks
           HTML
         end
 
+        # Renders the navigation rail: the domain name, a search box, and one
+        # link per section.
+        #
+        # @param title [String] the document's `#` heading text, `"Domain — Glossary"`
+        # @param sections [Array<Hash{Symbol => Object}>] every `##` section (the
+        #   front matter excluded)
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [String] the rail's HTML source
         def rail(title, sections, slugs)
           domain = title.split(" — ").first
           items = sections.map do |section|
@@ -167,6 +213,10 @@ module Hecks
           HTML
         end
 
+        # Renders the page's `<header>`: the title, vision, lede, and overview diagram.
+        #
+        # @param blocks [Array<Block>] the front matter's own blocks
+        # @return [String] the header's HTML source
         def front_matter(blocks)
           parts = ["<header>"]
           blocks.each do |block|
@@ -185,6 +235,11 @@ module Hecks
         # rules list), then its terms — each `###` opens an article that
         # runs to the next. A bold-only paragraph is the caption of
         # whatever figure or list follows it.
+        #
+        # @param section [Hash{Symbol => Object}] one `##` section, as `split_sections`
+        #   builds
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [String] the section's `<section>` HTML source
         def section_html(section, slugs)
           heading = section[:heading]
           state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{inline(heading.text)}</h2>"],
@@ -195,6 +250,15 @@ module Hecks
           state[:parts].join("\n")
         end
 
+        # Renders one block into `state[:parts]`, mutating `state` as it goes.
+        #
+        # @param block [Block] the block to render
+        # @param state [Hash{Symbol => Object}] the section's own render state:
+        #   `:parts` (the growing `Array<String>` of HTML), `:caption` (a pending
+        #   bold-only paragraph's text, or nil), `:in_terms` (whether a `###` term
+        #   article is currently open)
+        # @param slugs [Hash{Block => String}] every heading block's own slug
+        # @return [void]
         def section_block(block, state, slugs)
           parts = state[:parts]
           case block.type
@@ -214,6 +278,13 @@ module Hecks
           end
         end
 
+        # Renders one paragraph, either capturing it as a pending caption (a
+        # bold-only line) or appending it to `state[:parts]`.
+        #
+        # @param text [String] the paragraph's own text
+        # @param state [Hash{Symbol => Object}] the section's own render state (see
+        #   `section_block`); `:caption` and `:parts` may be mutated
+        # @return [void]
         def paragraph(text, state)
           if text.match?(/\A\*\*[^*]+\*\*\z/)
             state[:caption] = text.delete("*")
@@ -223,6 +294,11 @@ module Hecks
           end
         end
 
+        # Renders a mermaid block as a `<figure>`, with an optional caption.
+        #
+        # @param block [Block] the `:mermaid` block to render
+        # @param caption [String, nil] the figure's caption text, or nil for none
+        # @return [String] the `<figure>`'s HTML source
         def figure(block, caption)
           parts = ["<figure>"]
           parts << "<figcaption>#{escape(caption)}</figcaption>" if caption
@@ -232,10 +308,18 @@ module Hecks
 
         # ── inline text ──────────────────────────────────────────────────
 
+        # Escapes text for HTML.
+        #
+        # @param text [Object, nil] the value to escape, rendered with `to_s`
+        # @return [String] `text`, HTML-escaped
         def escape(text) = Forms::Escape.html(text)
 
         # Escape first, so nothing in the prose ever becomes a tag; then
         # the three inline forms the Markdown uses, on the escaped text.
+        #
+        # @param text [String] the inline text to render
+        # @return [String] `text`, HTML-escaped, with `[x](#y)` links, `**bold**` and
+        #   `*italic*` spans converted to their HTML equivalents
         def inline(text)
           escape(text)
             .gsub(/\[([^\]]+)\]\(#([^)]+)\)/) { %(<a href="##{Regexp.last_match(2)}">#{Regexp.last_match(1)}</a>) }
@@ -243,6 +327,10 @@ module Hecks
             .gsub(/\*(.+?)\*/) { "<em>#{Regexp.last_match(1)}</em>" }
         end
 
+        # Reads one static asset file from beside this file.
+        #
+        # @param name [String] the asset's filename, such as `"page.css"`
+        # @return [String] the asset file's contents, read from beside this file
         def asset(name) = File.read(File.join(__dir__, name))
       end
     end

data/lib/hecks/projections/glossary/markdown.rb

@@ -6,7 +6,7 @@ require_relative "../statements"
 module Hecks
   module Projections
     module Glossary
-      # THE DOCUMENT ITSELF — `glossary.md`, the one source the page is
+      # **The document itself** — `glossary.md`, the one source the page is
       # rendered from. Written in the handful of Markdown constructs
       # GitHub renders as-is (headings, blockquotes, ```mermaid fences,
       # lists, in-page links), so the file is a complete, readable
@@ -39,14 +39,27 @@ module Hecks
 
         module_function
 
+        # Titles the document after its chapter.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to title after
+        # @return [String] the document's `#` heading text
         def title(bluebook) = "#{bluebook.name} — Glossary"
 
+        # Renders the full `glossary.md` document.
+        #
+        # @param document [Glossary::Document] the assembled document to render
+        # @return [String] the complete Markdown source, ending in a newline
         def render(document)
           parts = [header(document.bluebook)]
           parts += document.sections.map { |section| section_text(section, document) }
           "#{parts.join("\n\n")}\n"
         end
 
+        # Renders the document's title, vision blockquote, lede, and overview map.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to render a
+        #   header for
+        # @return [String] the header's Markdown source
         def header(bluebook)
           parts = ["# #{title(bluebook)}"]
           parts << "> #{bluebook.vision}" if bluebook.vision
@@ -55,6 +68,13 @@ module Hecks
           parts.join("\n\n")
         end
 
+        # Renders one `##` section: its opening (an aggregate's, or a standing
+        # group's blurb), followed by every term inside it.
+        #
+        # @param section [Glossary::Section] the section to render
+        # @param document [Glossary::Document] the document `section` belongs to,
+        #   for its bluebook and link index
+        # @return [String] the section's Markdown source
         def section_text(section, document)
           parts = ["## #{section.title}"]
           parts += section.aggregate ? opening(section.aggregate, document.bluebook) : ["> #{STANDING[section.name]}"]
@@ -62,8 +82,14 @@ module Hecks
           parts.join("\n\n")
         end
 
-        # What an aggregate IS, what it can be, how it fits and moves,
+        # What an aggregate is, what it can be, how it fits and moves,
         # and what is always true of it — before a single term.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to render an opening for
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter `aggregate` belongs
+        #   to, for drawing its context diagram
+        # @return [Array<String>] the opening's Markdown blocks, one per paragraph or
+        #   diagram, not yet joined
         def opening(aggregate, bluebook)
           parts = []
           parts << "> #{aggregate.description}" if aggregate.description
@@ -75,13 +101,19 @@ module Hecks
           parts
         end
 
-        # THE STATEMENTS PROJECTION'S OWN SENTENCES, SPOKEN. An invariant
+        # The statements projection's own sentences, spoken. An invariant
         # is the author's words and stays exactly so. A relationship
         # sentence is built mechanically from construct names ("An
         # ATMCard references an Account."), and a construct name is the
         # one thing this page never shows as an identifier — so each is
         # replaced with how it is said, whole-word, and nothing else in
         # the sentence is touched.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to gather rules for
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to read every
+        #   construct name from, for de-identifying relationship sentences
+        # @return [Array<String>] `aggregate`'s (and its entities') attribute and
+        #   invariant statements, spoken and deduplicated
         def always_true(aggregate, bluebook)
           names = bluebook.aggregates.flat_map { |other| [other.hecks_name, *other.entities.map(&:hecks_name)] }
           [aggregate, *aggregate.entities].flat_map do |holder|
@@ -90,14 +122,29 @@ module Hecks
           end.uniq
         end
 
+        # Replaces every whole-word construct name in `sentence` with how it is said.
+        #
+        # @param sentence [String] the sentence to de-identify
+        # @param names [Array<String>] every construct name to replace, whole-word
+        # @return [String] `sentence` with each name in `names` replaced by
+        #   `Naming.words(name)`
         def spoken(sentence, names)
           names.reduce(sentence) { |text, name| text.gsub(/\b#{Regexp.escape(name)}\b/, Naming.words(name)) }
         end
 
+        # Renders one term's `###` heading and its paragraphs.
+        #
+        # @param entry [Glossary::Entry] the term to render
+        # @param index [Glossary::Index] the document's link index
+        # @return [String] the term's Markdown source
         def term_text(entry, index)
           ["### #{entry.headword}", *Sentences.paragraphs(entry, index)].join("\n\n")
         end
 
+        # Wraps a Mermaid diagram's source in a fenced code block.
+        #
+        # @param source [String] a Mermaid diagram's own source
+        # @return [String] `source` wrapped in a ` ```mermaid ` fence
         def fence(source) = "```mermaid\n#{source}\n```"
       end
     end

data/lib/hecks/projections/glossary/mermaid.rb

@@ -3,7 +3,7 @@ require_relative "../../naming"
 module Hecks
   module Projections
     module Glossary
-      # THE THREE PICTURES THE GLOSSARY DRAWS, each kept to the handful of
+      # The three pictures the glossary draws, each kept to the handful of
       # things that matter — Evans' "three to five objects central to the
       # issue at hand", never the whole model at once.
       #
@@ -25,6 +25,10 @@ module Hecks
       module Mermaid
         module_function
 
+        # Draws the whole chapter's aggregates and which points at which.
+        #
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to draw
+        # @return [String] a Mermaid `flowchart LR` source
         def map(bluebook)
           names = bluebook.aggregates.map(&:hecks_name)
           lines = ["flowchart LR"]
@@ -39,6 +43,12 @@ module Hecks
           lines.join("\n")
         end
 
+        # Draws one aggregate, its entities, and its neighbours.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to focus on
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to find
+        #   neighbouring aggregates in
+        # @return [String] a Mermaid `flowchart LR` source
         def context(aggregate, bluebook)
           focus = aggregate.hecks_name
           lines = ["flowchart LR", node(focus, focus: true)]
@@ -58,6 +68,11 @@ module Hecks
           lines.uniq.join("\n")
         end
 
+        # Draws the states a holder can be in and what moves it between them.
+        #
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder whose
+        #   lifecycle to draw
+        # @return [String] a Mermaid `stateDiagram-v2` source
         def lifecycle(holder)
           lifecycle = holder.lifecycle
           lines = ["stateDiagram-v2"]
@@ -74,15 +89,33 @@ module Hecks
 
         # ── the facts drawn ──────────────────────────────────────────────
 
+        # Names a holder's own reference attributes.
+        #
+        # @param holder [Bluebook::Aggregate, Bluebook::Entity] the holder to
+        #   read reference attributes from
+        # @return [Array<Bluebook::Attribute>] `holder`'s own reference attributes
         def references(holder) = holder.attributes.select(&:reference?)
 
         # An entity is held as `list_of(LedgerEntry)` — the attribute
         # whose element type names one of the aggregate's own entities.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to read entity
+        #   attributes from
+        # @return [Array<Bluebook::Attribute>] attributes whose element type is one
+        #   of `aggregate`'s own entities
         def entities(aggregate)
           names = aggregate.entities.map(&:hecks_name)
           aggregate.attributes.select { |attribute| !attribute.reference? && names.include?(attribute.type.to_s) }
         end
 
+        # Finds every other aggregate that references `aggregate`.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to find pointers to
+        # @param bluebook [Bluebook::Behaviour::Chapter] the chapter to search other
+        #   aggregates in
+        # @return [Array<Array(Bluebook::Aggregate, Bluebook::Attribute)>] every other
+        #   aggregate's own reference attribute that targets `aggregate`, paired
+        #   with its holder
         def pointing_at(aggregate, bluebook)
           bluebook.aggregates.reject { |other| other.equal?(aggregate) }.flat_map do |other|
             references(other).select { |attribute| attribute.type.target_name == aggregate.hecks_name }
@@ -94,13 +127,28 @@ module Hecks
 
         # A node id the page source can carry without an identifier in
         # it — `n_atm_card`, never `n_ATMCard`.
+        #
+        # @param name [String, Symbol] the construct name to derive an id from
+        # @return [String] a Mermaid-safe node id, such as `"n_atm_card"`
         def id(name) = "n_#{Naming.snake(name).gsub(/[^a-z0-9_]/, '_')}"
 
+        # Renders one Mermaid node declaration.
+        #
+        # @param name [String, Symbol] the node's construct name
+        # @param focus [Boolean] whether to mark this node with the `focus` CSS class
+        # @return [String] a Mermaid node declaration line
         def node(name, focus: false)
           line = "    #{id(name)}[\"#{Naming.words(name)}\"]"
           focus ? "#{line}:::focus" : line
         end
 
+        # Renders one Mermaid edge declaration.
+        #
+        # @param from [String, Symbol] the source node's construct name
+        # @param attribute [Bluebook::Attribute] the attribute the edge is labelled after
+        # @param to [String, Symbol] the target node's construct name
+        # @return [String] a Mermaid edge declaration line, labelled with the
+        #   attribute's spoken name
         def edge(from, attribute, to)
           "    #{id(from)} -->|\"#{Naming.words(attribute.name).downcase}\"| #{id(to)}"
         end

data/lib/hecks/projections/glossary/sections.rb

@@ -1,7 +1,7 @@
 module Hecks
   module Projections
     module Glossary
-      # THE THREE SECTIONS NOTHING HOMES TO ONE AGGREGATE. In their own
+      # The three sections nothing homes to one aggregate. In their own
       # file because `Markdown` reads them and loads before the
       # projector's own body does.
       ROLES       = "Roles".freeze