hecks 1.2.0 → 1.4.0

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

@@ -0,0 +1,250 @@
+require_relative "../../forms/html"
+
+module Hecks
+  module Projections
+    module Glossary
+      # **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 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
+      # for six constructs would not earn one.
+      #
+      # The look lives in page.css / page.js beside this file — read at
+      # render time and inlined, so the page is one self-contained file.
+      # The only things it fetches are the two typefaces (Google Fonts)
+      # and Mermaid itself (cdnjs), which draws the diagrams in the
+      # browser; without a network the diagrams show as their source.
+      module Html
+        Block = Struct.new(:type, :text, :items, :level, keyword_init: true)
+
+        FONTS   = "https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;" \
+                  "0,6..72,600;1,6..72,400&family=Instrument+Sans:wght@400;500;600&display=swap".freeze
+        MERMAID = "https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js".freeze
+
+        module_function
+
+        def render(markdown)
+          blocks = parse(markdown)
+          slugs  = heading_slugs(blocks)
+          title  = blocks.find { |block| block.type == :heading && block.level == 1 }&.text.to_s
+          sections = split_sections(blocks)
+          page(title, sections, slugs)
+        end
+
+        # ── reading the Markdown ─────────────────────────────────────────
+
+        def parse(markdown)
+          lines  = markdown.lines.map(&:chomp)
+          blocks = []
+          index  = 0
+          while index < lines.size
+            line = lines[index]
+            if line.start_with?("```mermaid")
+              block, index = fence(lines, index)
+              blocks << block
+            elsif (heading = line.match(/\A(\#{1,3}) (.+)\z/))
+              blocks << Block.new(type: :heading, text: heading[2], level: heading[1].size)
+              index += 1
+            elsif line.start_with?("> ")
+              blocks << Block.new(type: :quote, text: line[2..])
+              index += 1
+            elsif line.start_with?("- ")
+              items, index = run(lines, index) { |text| text.start_with?("- ") }
+              blocks << Block.new(type: :list, items: items.map { |item| item[2..] })
+            elsif line.strip.empty?
+              index += 1
+            else
+              para, index = run(lines, index) { |text| !text.strip.empty? }
+              blocks << Block.new(type: :paragraph, text: para.join(" "))
+            end
+          end
+          blocks
+        end
+
+        # The mermaid source between the opening fence at `index` and its
+        # closing one, and the index just past that.
+        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]
+        end
+
+        # The consecutive lines from `index` that satisfy the block, and
+        # the index just past them.
+        def run(lines, index)
+          taken = []
+          while index < lines.size && yield(lines[index])
+            taken << lines[index]
+            index += 1
+          end
+          [taken, index]
+        end
+
+        # 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
+        # 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.
+        def heading_slugs(blocks)
+          seen  = Hash.new(0)
+          slugs = {}.compare_by_identity
+          blocks.select { |block| block.type == :heading }.each do |block|
+            base = Slugs.github(block.text)
+            seen[base] += 1
+            slugs[block] = seen[base] == 1 ? base : "#{base}-#{seen[base] - 1}"
+          end
+          slugs
+        end
+
+        # Everything before the first `##` is the front matter; each `##`
+        # opens a section that runs to the next.
+        def split_sections(blocks)
+          sections = [{ heading: nil, blocks: [] }]
+          blocks.each do |block|
+            sections << { heading: block, blocks: [] } if block.type == :heading && block.level == 2
+            sections.last[:blocks] << block
+          end
+          sections
+        end
+
+        # ── writing the page ─────────────────────────────────────────────
+
+        def page(title, sections, slugs)
+          front, *rest = sections
+          <<~HTML
+            <!doctype html>
+            <html lang="en">
+            <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>#{escape(title)}</title>
+            <link rel="stylesheet" href="#{FONTS}">
+            <script src="#{MERMAID}"></script>
+            <style>
+            #{asset('page.css')}
+            </style>
+            </head>
+            <body>
+            <div class="page">
+            #{rail(title, rest, slugs)}
+            <main>
+            #{front_matter(front[:blocks])}
+            #{rest.map { |section| section_html(section, slugs) }.join("\n")}
+            </main>
+            </div>
+            <script>
+            #{asset('page.js')}
+            </script>
+            </body>
+            </html>
+          HTML
+        end
+
+        def rail(title, sections, slugs)
+          domain = title.split(" — ").first
+          items = sections.map do |section|
+            heading = section[:heading]
+            %(<li><a href="##{slugs[heading]}">#{inline(heading.text)}</a></li>)
+          end
+          <<~HTML
+            <nav class="rail" aria-label="Sections">
+            <p class="domain">#{escape(domain)}</p>
+            <p class="sub">Glossary</p>
+            <input type="search" placeholder="Find a term" aria-label="Find a term" autocomplete="off">
+            <p class="count"></p>
+            <ol>
+            #{items.join("\n")}
+            </ol>
+            </nav>
+          HTML
+        end
+
+        def front_matter(blocks)
+          parts = ["<header>"]
+          blocks.each do |block|
+            case block.type
+            when :heading   then parts << "<h1>#{inline(block.text.split(' — ').first)}</h1>"
+            when :quote     then parts << "<p class=\"vision\">#{inline(block.text)}</p>"
+            when :paragraph then parts << "<p class=\"lede\">#{inline(block.text)}</p>"
+            when :mermaid   then parts << figure(block, "How it all fits together")
+            end
+          end
+          parts << "</header>"
+          parts.join("\n")
+        end
+
+        # A section is its heading, then its opening (lede, diagrams, the
+        # 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.
+        def section_html(section, slugs)
+          heading = section[:heading]
+          state = { parts: [%(<section id="#{slugs[heading]}">), "<h2>#{inline(heading.text)}</h2>"],
+                    caption: nil, in_terms: false }
+          section[:blocks].drop(1).each { |block| section_block(block, state, slugs) }
+          state[:parts] << "</article></div>" if state[:in_terms]
+          state[:parts] << "</section>"
+          state[:parts].join("\n")
+        end
+
+        def section_block(block, state, slugs)
+          parts = state[:parts]
+          case block.type
+          when :heading
+            parts << (state[:in_terms] ? "</article>" : "<div class=\"terms\">")
+            parts << %(<article class="term" id="#{slugs[block]}">) << "<h3>#{inline(block.text)}</h3>"
+            state[:in_terms] = true
+          when :mermaid
+            parts << figure(block, state.delete(:caption))
+          when :list
+            parts << "<p class=\"caption\">#{escape(state[:caption])}</p>" if state.delete(:caption)
+            parts << "<ul class=\"rules\">#{block.items.map { |item| "<li>#{inline(item)}</li>" }.join}</ul>"
+          when :quote
+            parts << "<p class=\"about\">#{inline(block.text)}</p>"
+          when :paragraph
+            paragraph(block.text, state)
+          end
+        end
+
+        def paragraph(text, state)
+          if text.match?(/\A\*\*[^*]+\*\*\z/)
+            state[:caption] = text.delete("*")
+          else
+            klass = text.start_with?("Always true:") ? " class=\"rule\"" : ""
+            state[:parts] << "<p#{klass}>#{inline(text)}</p>"
+          end
+        end
+
+        def figure(block, caption)
+          parts = ["<figure>"]
+          parts << "<figcaption>#{escape(caption)}</figcaption>" if caption
+          parts << "<pre class=\"mermaid\">#{escape(block.text)}</pre>" << "</figure>"
+          parts.join("\n")
+        end
+
+        # ── inline text ──────────────────────────────────────────────────
+
+        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.
+        def inline(text)
+          escape(text)
+            .gsub(/\[([^\]]+)\]\(#([^)]+)\)/) { %(<a href="##{Regexp.last_match(2)}">#{Regexp.last_match(1)}</a>) }
+            .gsub(/\*\*(.+?)\*\*/) { "<strong>#{Regexp.last_match(1)}</strong>" }
+            .gsub(/\*(.+?)\*/) { "<em>#{Regexp.last_match(1)}</em>" }
+        end
+
+        def asset(name) = File.read(File.join(__dir__, name))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+require_relative "sections"
+require_relative "sentences"
+require_relative "mermaid"
+require_relative "../statements"
+
+module Hecks
+  module Projections
+    module Glossary
+      # **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
+      # glossary on its own before any page is built from it:
+      #
+      #   # Banking — Glossary
+      #   > vision
+      #   lede
+      #   ```mermaid          the map
+      #   ## Account
+      #   > description
+      #   Starts out open. Can be open, frozen, or closed.
+      #   **How it fits**     ```mermaid
+      #   **How it moves**    ```mermaid
+      #   **Always true**     - one sentence per declared fact
+      #   ### Account number  one ### per term, A to Z
+      #   Made up of a value (text).
+      #   Always true: an account number is present.
+      module Markdown
+        LEDE = "Every term %<name>s uses, in the words of the people who work in it — grouped under the thing " \
+               "each belongs to, and listed A to Z within it. This page is generated from the working " \
+               "specification, so it says what the system does today, not what anyone hoped it would do. " \
+               "If a sentence here reads wrong to you, the specification is wrong: say so.".freeze
+
+        STANDING = {
+          ROLES       => "Who does what. A role is named once here rather than under every term it touches.",
+          READ_MODELS => "Questions answered across more than one of the things above.",
+          REACTIONS   => "What happens on its own, in response to something this specification does not itself raise."
+        }.freeze
+
+        module_function
+
+        def title(bluebook) = "#{bluebook.name} — Glossary"
+
+        def render(document)
+          parts = [header(document.bluebook)]
+          parts += document.sections.map { |section| section_text(section, document) }
+          "#{parts.join("\n\n")}\n"
+        end
+
+        def header(bluebook)
+          parts = ["# #{title(bluebook)}"]
+          parts << "> #{bluebook.vision}" if bluebook.vision
+          parts << format(LEDE, name: bluebook.name)
+          parts << fence(Mermaid.map(bluebook))
+          parts.join("\n\n")
+        end
+
+        def section_text(section, document)
+          parts = ["## #{section.title}"]
+          parts += section.aggregate ? opening(section.aggregate, document.bluebook) : ["> #{STANDING[section.name]}"]
+          parts += section.terms.map { |entry| term_text(entry, document.index) }
+          parts.join("\n\n")
+        end
+
+        # What an aggregate is, what it can be, how it fits and moves,
+        # and what is always true of it — before a single term.
+        def opening(aggregate, bluebook)
+          parts = []
+          parts << "> #{aggregate.description}" if aggregate.description
+          parts << Sentences.lifecycle_sentence(aggregate.lifecycle) if aggregate.lifecycle
+          parts << "**How it fits**" << fence(Mermaid.context(aggregate, bluebook))
+          parts << "**How it moves**" << fence(Mermaid.lifecycle(aggregate)) if aggregate.lifecycle
+          statements = always_true(aggregate, bluebook)
+          parts << "**Always true**" << statements.map { |statement| "- #{statement}" }.join("\n") unless statements.empty?
+          parts
+        end
+
+        # 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.
+        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|
+            Statements.attribute_statements(holder).map { |sentence| spoken(sentence, names) } +
+              Statements.invariant_statements(holder)
+          end.uniq
+        end
+
+        def spoken(sentence, names)
+          names.reduce(sentence) { |text, name| text.gsub(/\b#{Regexp.escape(name)}\b/, Naming.words(name)) }
+        end
+
+        def term_text(entry, index)
+          ["### #{entry.headword}", *Sentences.paragraphs(entry, index)].join("\n\n")
+        end
+
+        def fence(source) = "```mermaid\n#{source}\n```"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+require_relative "../../naming"
+
+module Hecks
+  module Projections
+    module Glossary
+      # 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.
+      #
+      #   map        the aggregates and which points at which — one small
+      #              graph at the top, for the reader who wants the shape
+      #              of the domain before its words.
+      #   context    one aggregate, its entities, and the neighbours it
+      #              points at or is pointed at by. Value objects are
+      #              words in the text ("Made up of …"), not boxes here —
+      #              Account alone has eight, and eight boxes say less
+      #              than one sentence.
+      #   lifecycle  the states a thing can be in and what moves it.
+      #
+      # Every label is a person's spelling (`Naming.words`), and the
+      # edges read from the same declared facts `Projections::Diagrams`
+      # draws its own from (`reference?`, `type.target_name`, `name`,
+      # `lifecycle.transitions`) — a different picture of the same
+      # declaration, not a second declaration.
+      module Mermaid
+        module_function
+
+        def map(bluebook)
+          names = bluebook.aggregates.map(&:hecks_name)
+          lines = ["flowchart LR"]
+          names.each { |name| lines << node(name) }
+          bluebook.aggregates.each do |aggregate|
+            references(aggregate).each do |attribute|
+              target = attribute.type.target_name
+              lines << node(target) unless names.include?(target) || lines.include?(node(target))
+              lines << edge(aggregate.hecks_name, attribute, target)
+            end
+          end
+          lines.join("\n")
+        end
+
+        def context(aggregate, bluebook)
+          focus = aggregate.hecks_name
+          lines = ["flowchart LR", node(focus, focus: true)]
+          entities(aggregate).each do |attribute|
+            lines << node(attribute.type.to_s)
+            lines << edge(focus, attribute, attribute.type.to_s)
+          end
+          references(aggregate).each do |attribute|
+            lines << node(attribute.type.target_name)
+            lines << edge(focus, attribute, attribute.type.target_name)
+          end
+          pointing_at(aggregate, bluebook).each do |holder, attribute|
+            lines << node(holder.hecks_name)
+            lines << edge(holder.hecks_name, attribute, focus)
+          end
+          lines << "    classDef focus stroke-width:3px"
+          lines.uniq.join("\n")
+        end
+
+        def lifecycle(holder)
+          lifecycle = holder.lifecycle
+          lines = ["stateDiagram-v2"]
+          states = ([lifecycle.default] + lifecycle.transitions.map { |_name, transition| transition.target }).uniq
+          states.select { |state| state.to_s.include?("_") }.each do |state|
+            lines << "    state \"#{state.to_s.tr('_', ' ')}\" as #{state}"
+          end
+          lines << "    [*] --> #{lifecycle.default}"
+          lifecycle.transitions.each do |name, transition|
+            Array(transition.from).each { |from| lines << "    #{from} --> #{transition.target}: #{Naming.words(name)}" }
+          end
+          lines.join("\n")
+        end
+
+        # ── the facts drawn ──────────────────────────────────────────────
+
+        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.
+        def entities(aggregate)
+          names = aggregate.entities.map(&:hecks_name)
+          aggregate.attributes.select { |attribute| !attribute.reference? && names.include?(attribute.type.to_s) }
+        end
+
+        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 }
+                             .map { |attribute| [other, attribute] }
+          end
+        end
+
+        # ── the drawing ──────────────────────────────────────────────────
+
+        # A node id the page source can carry without an identifier in
+        # it — `n_atm_card`, never `n_ATMCard`.
+        def id(name) = "n_#{Naming.snake(name).gsub(/[^a-z0-9_]/, '_')}"
+
+        def node(name, focus: false)
+          line = "    #{id(name)}[\"#{Naming.words(name)}\"]"
+          focus ? "#{line}:::focus" : line
+        end
+
+        def edge(from, attribute, to)
+          "    #{id(from)} -->|\"#{Naming.words(attribute.name).downcase}\"| #{id(to)}"
+        end
+      end
+    end
+  end
+end