hecks 1.1.0 → 1.3.0

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

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

@@ -0,0 +1,205 @@
+require_relative "../../naming"
+require_relative "../statements"
+
+module Hecks
+  module Projections
+    module Glossary
+      # EVERY SENTENCE THE GLOSSARY SAYS, AND THE RULE EACH ONE OBEYS.
+      #
+      # Authored text is verbatim: an aggregate's `description`, a
+      # command's `goal`, a query's `description`, an invariant's own
+      # words. Derived text is mechanical, from one declared fact, in a
+      # shape a reader outside engineering would say — "Recorded after
+      # Freeze account", "Made up of an amount (a whole number) and a
+      # currency (text)". Nothing is paraphrased and nothing is guessed:
+      # a fact with no honest plain phrasing gets no sentence (the
+      # `DocsProjector` rule — a wrong sentence is worse than none).
+      #
+      # Cross-references come only from declared structure (a command's
+      # `emits:`, a policy's `on`/`trigger`), resolved through the
+      # document's `Index`; free prose is never searched for words to
+      # link. A reference the chapter does not declare (a cross-domain
+      # command) is spoken as plain words.
+      module Sentences
+        TYPE_WORDS = {
+          "Integer" => "a whole number", "Float" => "a number", "String" => "text",
+          "Boolean" => "yes or no", "TrueClass" => "yes or no", "FalseClass" => "yes or no"
+        }.freeze
+
+        module_function
+
+        # The paragraphs under a term's headword — the definition first,
+        # then, when the term carries rules, one "Always true: …" line.
+        def paragraphs(entry, index)
+          facts = entry.facts
+          case entry.kind
+          when :entity       then holder_paragraphs(facts[:entity])
+          when :value_object then value_object_paragraphs(facts[:value_object], index, entry.within)
+          when :command      then [command_sentence(facts[:command])]
+          when :query        then [facts[:query].description]
+          when :event        then [event_sentence(facts, index)]
+          when :policy       then [policy_sentence(facts[:policy], index)]
+          when :saga         then [saga_sentence(facts[:saga], index)]
+          when :role         then [role_sentence(facts[:commands], index)]
+          when :read_model   then [facts[:read_model].description]
+          end.compact
+        end
+
+        # An aggregate's lede or an entity's entry: what it is, then the
+        # states it can be in.
+        def holder_paragraphs(holder)
+          [holder.description, holder.lifecycle && lifecycle_sentence(holder.lifecycle)].compact
+        end
+
+        def lifecycle_sentence(lifecycle)
+          states = ([lifecycle.default] + lifecycle.transitions.map { |_name, transition| transition.target }).uniq
+          "Starts out #{spoken(lifecycle.default)}. " \
+            "Can be #{Naming.to_sentence_list(states.map { |state| spoken(state) }, conj: 'or')}."
+        end
+
+        # A state name is spelled `awaiting_credit`; said, it is "awaiting credit".
+        def spoken(state) = state.to_s.tr("_", " ")
+
+        def value_object_paragraphs(value_object, index, within)
+          rules = value_object.invariants.map { |invariant| Statements.invariant_statement(invariant) }
+          [value_object_sentence(value_object, index, within), rules_line(rules)].compact
+        end
+
+        # A one-field object whose field is just "value" IS its type —
+        # "Text.", "A whole number." — the field name would add nothing.
+        def value_object_sentence(value_object, index, within)
+          return closed_set_sentence(value_object.members) if value_object.closed_set?
+          return "A marker with no details of its own." if value_object.attributes.empty?
+
+          only = value_object.attributes.first
+          if value_object.attributes.size == 1 && only.name.to_s == "value"
+            return "#{upper_first(type_words(only, index, within))}."
+          end
+
+          fields = value_object.attributes.map { |field| field_phrase(field, index, within) }
+          "Made up of #{Naming.to_sentence_list(fields)}."
+        end
+
+        # "amount (a whole number)" — the field as the author named it,
+        # then what kind of thing goes in it.
+        def field_phrase(field, index, within)
+          "#{Naming.words(field.name).downcase} (#{type_words(field, index, within)})"
+        end
+
+        def type_words(field, index, within)
+          type  = field.type.to_s
+          inner = TYPE_WORDS[type] || index.link(:value_object, type, within: within)
+          field.list? ? "a list of #{inner}" : inner
+        end
+
+        # A CLOSED SET'S ROWS — a one-field set is its values; a set
+        # whose rows carry more (StatementFrequency's cadence plus a
+        # retention and a fee) leads with the first field and keeps the
+        # rest beside it, so no row loses what makes it distinct.
+        def closed_set_sentence(members)
+          if members.first && members.first.size > 1
+            rows = members.map do |row|
+              lead, *rest = row.map { |field, value| [field, value] }
+              "#{lead.last} (#{rest.map { |field, value| "#{Naming.words(field).downcase} #{value}" }.join(', ')})"
+            end
+            "One of: #{rows.join('; ')}."
+          else
+            "One of #{Naming.to_sentence_list(members.flat_map(&:values).uniq.map(&:to_s), conj: 'or')}."
+          end
+        end
+
+        # "Always true: an amount is positive; a currency is a three-letter
+        # code." — the rules as their author wrote them, kept out of the
+        # definition sentence (a rule hidden inside a definition is a rule
+        # a reader misses).
+        def rules_line(rules)
+          return nil if rules.empty?
+
+          clauses = rules.map { |rule| lower_first(rule.sub(/\.\z/, "")) }
+          "Always true: #{clauses.join('; ')}."
+        end
+
+        def command_sentence(command)
+          parts = []
+          parts << with_period(command.goal) if command.goal
+          parts << "Done by the #{Naming.words(command.role).downcase}." if command.role
+          parts.empty? ? nil : parts.join(" ")
+        end
+
+        def event_sentence(facts, index)
+          raisers = command_links(facts[:raised_by], index)
+          sentence = "Recorded after #{Naming.to_sentence_list(raisers, conj: 'or')}."
+          reactions = facts[:policies].map { |policy| index.link(:policy, policy.name) }
+          sentence += " Prompts #{Naming.to_sentence_list(reactions)}." unless reactions.empty?
+          sentence
+        end
+
+        # "When Customer suspended happens, Account is asked to Freeze
+        # account, once for each row of Open for customer." — a
+        # cross-domain trigger (`across "Compliance"`) is spoken as words
+        # with the domain named, since nothing here to link to exists.
+        def policy_sentence(policy, index)
+          holder, command = split_trigger(policy.trigger_command)
+          asked = if policy.target_domain
+                    "#{Naming.words(holder)} is asked to #{Naming.words(command).downcase}, " \
+                      "in #{Naming.words(policy.target_domain)}"
+                  else
+                    "#{index.link(:aggregate, holder)} is asked to #{index.link(:command, command, within: holder)}"
+                  end
+          sentence = "When #{index.link(:event, bare(policy.on_event))} happens, #{asked}"
+          if policy.for_each
+            query_holder, query = split_trigger(policy.for_each)
+            sentence += ", once for each row of #{index.link(:query, query, within: query_holder)}"
+          end
+          "#{sentence}."
+        end
+
+        def saga_sentence(shape, index)
+          sentence = "Begins when #{index.link(:event, bare(shape[:starts_on]))} happens " \
+                     "and ends when #{index.link(:event, bare(shape[:ends_on]))} happens."
+          states = Array(shape[:states]).map { |state| spoken(state) }
+          sentence += " Along the way it can be #{Naming.to_sentence_list(states, conj: 'or')}." unless states.empty?
+          sentence
+        end
+
+        # A NOUN LIST, DELIBERATELY — "Responsible for Credit and Debit",
+        # never "Can credit and debit": banking's System role raises
+        # `Debited` and `Credited`, and "can … debited" is a wrong
+        # sentence. The headwords are already what people say.
+        def role_sentence(issues, index)
+          "Responsible for #{Naming.to_sentence_list(command_links(issues, index))}."
+        end
+
+        # THE SAME WORD FOR TWO DIFFERENT THINGS gets its holder beside it
+        # — a role responsible for CardPayment's Reverse and Transfer's
+        # Reverse is responsible for "Reverse (card payment)" and
+        # "Reverse (transfer)", not for "Reverse" twice.
+        def command_links(issues, index)
+          issues = issues.uniq { |holder, command| [holder.hecks_name, command.hecks_name] }
+          repeated = issues.map { |_holder, command| command.hecks_name }.tally.select { |_name, count| count > 1 }
+          issues.map do |holder, command|
+            label = if repeated.key?(command.hecks_name)
+                      "#{Naming.words(command.hecks_name)} (#{Naming.words(holder.hecks_name).downcase})"
+                    end
+            index.link(:command, command.hecks_name, within: holder.hecks_name, label: label)
+          end
+        end
+
+        # ── small carpentry ─────────────────────────────────────────────
+
+        def split_trigger(dotted)
+          holder, _dot, command = dotted.to_s.rpartition(".")
+          [holder, command]
+        end
+
+        def bare(qualified) = qualified.to_s.split(".").last
+
+        def with_period(text) = text.to_s.strip.end_with?(".", "!", "?") ? text.to_s.strip : "#{text.to_s.strip}."
+
+        def lower_first(text) = text.sub(/\A[[:upper:]]/, &:downcase)
+
+        def upper_first(text) = text.sub(/\A[[:lower:]]/, &:upcase)
+      end
+    end
+  end
+end