hecks 1.2.0 → 1.3.0

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

data/lib/hecks/projections/glossary/page.css

@@ -0,0 +1,271 @@
+/* The glossary page. Ledger paper: faint blue horizontal rules between
+   entries, one red vertical margin rule down the navigation. The rules
+   carry information — the red marks the section in view, the blue
+   separates entries — and nothing else on the page is decoration. */
+
+:root {
+  --paper: #f3f5f8;
+  --panel: #ffffff;
+  --ink: #1a2b4a;
+  --ink-soft: #4a5873;
+  --ink-faint: #8592a8;
+  --rule: #c9d3e3;
+  --red: #b0413e;
+  --red-wash: rgba(176, 65, 62, 0.09);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --paper: #0f1726;
+    --panel: #141e33;
+    --ink: #e3e7ee;
+    --ink-soft: #b4bdd0;
+    --ink-faint: #7f8ba6;
+    --rule: #2a3854;
+    --red: #d9635f;
+    --red-wash: rgba(217, 99, 95, 0.14);
+  }
+}
+
+:root[data-theme="dark"] {
+  --paper: #0f1726;
+  --panel: #141e33;
+  --ink: #e3e7ee;
+  --ink-soft: #b4bdd0;
+  --ink-faint: #7f8ba6;
+  --rule: #2a3854;
+  --red: #d9635f;
+  --red-wash: rgba(217, 99, 95, 0.14);
+}
+
+html { color-scheme: light dark; scroll-behavior: smooth; }
+
+body {
+  margin: 0;
+  background: var(--paper);
+  color: var(--ink);
+  font-family: "Newsreader", Georgia, "Times New Roman", serif;
+  font-size: 17px;
+  line-height: 1.55;
+  font-variant-numeric: oldstyle-nums;
+}
+
+a { color: var(--red); }
+:focus-visible { outline: 2px solid var(--red); outline-offset: 2px; }
+
+.page {
+  display: grid;
+  grid-template-columns: 15.5rem minmax(0, 1fr);
+  min-height: 100vh;
+}
+
+/* ── the rail ───────────────────────────────────────────────────── */
+
+.rail {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  box-sizing: border-box;
+  overflow-y: auto;
+  padding: 2.4rem 1.3rem 2rem 1.6rem;
+  border-right: 1px solid var(--rule);
+  font-family: "Instrument Sans", system-ui, -apple-system, sans-serif;
+  font-size: 0.92rem;
+}
+
+.rail .domain {
+  font-family: "Newsreader", Georgia, serif;
+  font-size: 1.55rem;
+  font-weight: 600;
+  line-height: 1.1;
+  margin: 0;
+}
+
+.rail .sub { color: var(--ink-faint); margin: 0.15rem 0 1.4rem; font-size: 0.82rem; }
+
+.rail input {
+  width: 100%;
+  box-sizing: border-box;
+  font: inherit;
+  padding: 0.45rem 0.65rem;
+  border: 1px solid var(--rule);
+  border-radius: 4px;
+  background: var(--panel);
+  color: var(--ink);
+}
+
+.rail input::placeholder { color: var(--ink-faint); }
+
+.rail .count { color: var(--ink-faint); font-size: 0.78rem; margin: 0.45rem 0 1.2rem; }
+
+.rail ol {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  border-left: 2px solid var(--red);
+}
+
+.rail li a {
+  display: block;
+  padding: 0.28rem 0.85rem;
+  margin-left: -2px;
+  border-left: 2px solid transparent;
+  color: var(--ink-soft);
+  text-decoration: none;
+}
+
+.rail li a:hover { color: var(--ink); }
+
+.rail li a[aria-current="true"] {
+  color: var(--ink);
+  font-weight: 600;
+  border-left-color: var(--ink);
+}
+
+/* ── the text column ────────────────────────────────────────────── */
+
+main {
+  padding: 3.2rem 4rem 7rem 3.6rem;
+  max-width: 47rem;
+}
+
+header h1 {
+  font-size: 3rem;
+  font-weight: 500;
+  line-height: 1.02;
+  letter-spacing: -0.012em;
+  margin: 0 0 1.1rem;
+}
+
+.vision {
+  font-size: 1.28rem;
+  font-style: italic;
+  line-height: 1.45;
+  color: var(--ink-soft);
+  margin: 0 0 1.2rem;
+}
+
+.lede { color: var(--ink-soft); margin: 0 0 1.6rem; max-width: 62ch; }
+
+figure { margin: 1.2rem 0 1.8rem; }
+
+figcaption, .caption {
+  font-family: "Instrument Sans", system-ui, sans-serif;
+  font-size: 0.8rem;
+  color: var(--ink-faint);
+  margin: 0 0 0.4rem;
+}
+
+.caption { margin-top: 1.6rem; }
+
+pre.mermaid {
+  margin: 0;
+  padding: 1rem 1.2rem;
+  background: var(--panel);
+  border: 1px solid var(--rule);
+  border-radius: 6px;
+  overflow-x: auto;
+  font-family: "Instrument Sans", system-ui, sans-serif;
+  font-size: 0.85rem;
+  line-height: 1.4;
+  color: var(--ink-soft);
+}
+
+pre.mermaid svg { display: block; max-width: 100%; height: auto; }
+
+section { margin-top: 4.5rem; scroll-margin-top: 1.5rem; }
+
+section h2 {
+  display: inline-block;
+  font-size: 2.1rem;
+  font-weight: 500;
+  line-height: 1.1;
+  margin: 0 0 0.5rem;
+  padding-bottom: 0.3rem;
+  border-bottom: 2px solid var(--red);
+}
+
+.about {
+  font-size: 1.18rem;
+  color: var(--ink-soft);
+  margin: 0.5rem 0 0.7rem;
+  max-width: 60ch;
+}
+
+section > p:not(.about):not(.caption) { margin: 0 0 0.8rem; max-width: 62ch; }
+
+.rules {
+  list-style: none;
+  margin: 0 0 1.2rem;
+  padding: 0;
+  max-width: 62ch;
+}
+
+.rules li {
+  padding: 0.38rem 0;
+  border-bottom: 1px solid var(--rule);
+}
+
+.terms { margin-top: 1.8rem; border-top: 1px solid var(--rule); }
+
+.term {
+  display: grid;
+  grid-template-columns: 12.5rem minmax(0, 1fr);
+  column-gap: 1.6rem;
+  padding: 0.9rem 0;
+  border-bottom: 1px solid var(--rule);
+  scroll-margin-top: 1.5rem;
+}
+
+.term h3 {
+  font-size: 1.08rem;
+  font-weight: 600;
+  line-height: 1.35;
+  margin: 0.05rem 0 0;
+}
+
+.term p { margin: 0 0 0.4rem; }
+.term p:last-child { margin-bottom: 0; }
+
+.term p.rule { color: var(--ink-soft); font-size: 0.95rem; }
+
+.term a, .rules a {
+  color: var(--red);
+  font-style: italic;
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+}
+
+/* A search narrows the page to the terms that match. */
+section.searching figure,
+section.searching .rules,
+section.searching .caption,
+section.searching .about,
+section.searching > p { display: none; }
+
+section.searching .terms { border-top: 0; margin-top: 0.8rem; }
+
+/* Landing on a term from a link. */
+.landed { animation: land 1.4s ease-out; }
+
+@keyframes land {
+  from { background: var(--red-wash); }
+  to { background: transparent; }
+}
+
+@media (max-width: 760px) {
+  .page { grid-template-columns: 1fr; }
+  .rail { position: static; height: auto; border-right: 0; border-bottom: 1px solid var(--rule); }
+  .rail ol { display: flex; flex-wrap: wrap; gap: 0.2rem 0.6rem; border-left: 0; }
+  .rail li a { padding: 0.2rem 0.4rem; border-left: 0; }
+  .rail li a[aria-current="true"] { border-bottom: 2px solid var(--red); }
+  main { padding: 1.8rem 1.2rem 4rem; }
+  header h1 { font-size: 2.3rem; }
+  .term { grid-template-columns: 1fr; row-gap: 0.25rem; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html { scroll-behavior: auto; }
+  .landed { animation: none; }
+}

data/lib/hecks/projections/glossary/page.js

@@ -0,0 +1,72 @@
+// The page's three behaviours: draw the diagrams, find a term, and
+// keep the rail pointing at the section in view. Nothing here changes
+// what the page says — that is all in the Markdown it was rendered from.
+(function () {
+  var root = document.documentElement;
+  var dark = root.dataset.theme === "dark" ||
+    (root.dataset.theme !== "light" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+
+  if (window.mermaid) {
+    mermaid.initialize({
+      startOnLoad: true,
+      theme: dark ? "dark" : "neutral",
+      fontFamily: "\"Instrument Sans\", system-ui, sans-serif",
+      flowchart: { curve: "basis", padding: 12 }
+    });
+  }
+
+  var input = document.querySelector(".rail input");
+  var count = document.querySelector(".rail .count");
+  var terms = Array.prototype.slice.call(document.querySelectorAll(".term"));
+  var sections = Array.prototype.slice.call(document.querySelectorAll("main section"));
+  var links = {};
+  Array.prototype.forEach.call(document.querySelectorAll(".rail a"), function (a) {
+    links[a.getAttribute("href").slice(1)] = a;
+  });
+
+  function filter() {
+    var query = input.value.trim().toLowerCase();
+    var shown = 0;
+    terms.forEach(function (term) {
+      var hit = !query || term.textContent.toLowerCase().indexOf(query) !== -1;
+      term.hidden = !hit;
+      if (hit) shown += 1;
+    });
+    sections.forEach(function (section) {
+      var any = Array.prototype.some.call(section.querySelectorAll(".term"), function (t) { return !t.hidden; });
+      section.hidden = !!query && !any;
+      section.classList.toggle("searching", !!query);
+      var link = links[section.id];
+      if (link) link.parentNode.hidden = section.hidden;
+    });
+    count.textContent = query ? shown + " of " + terms.length + " terms" : terms.length + " terms";
+  }
+
+  input.addEventListener("input", filter);
+  filter();
+
+  if ("IntersectionObserver" in window) {
+    var observer = new IntersectionObserver(function (entries) {
+      entries.forEach(function (entry) {
+        if (!entry.isIntersecting) return;
+        Object.keys(links).forEach(function (id) { links[id].removeAttribute("aria-current"); });
+        var link = links[entry.target.id];
+        if (link) link.setAttribute("aria-current", "true");
+      });
+    }, { rootMargin: "-8% 0px -82% 0px" });
+    sections.forEach(function (section) { observer.observe(section); });
+  }
+
+  // A link inside a definition lands on a term; a search in progress
+  // would hide it, so the search is cleared first.
+  document.addEventListener("click", function (event) {
+    var a = event.target.closest && event.target.closest("a[href^='#']");
+    if (!a) return;
+    var target = document.getElementById(a.getAttribute("href").slice(1));
+    if (!target) return;
+    if (input.value) { input.value = ""; filter(); }
+    target.classList.remove("landed");
+    void target.offsetWidth;
+    target.classList.add("landed");
+  });
+})();

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

@@ -0,0 +1,17 @@
+module Hecks
+  module Projections
+    module Glossary
+      # 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
+      READ_MODELS = "Read models".freeze
+      # Where a term lands when the fact it hangs on is raised by nothing
+      # this chapter declares — pizzas' `PizzaPaymentReceived` comes in
+      # through a port, so the policy reacting to it homes to no
+      # aggregate. Shown, not dropped: a visible blank is how a reader
+      # learns the language has a gap there.
+      REACTIONS   = "Reactions".freeze
+    end
+  end
+end