hecks 1.3.0 → 1.5.0

data/lib/hecks/projections/statements.rb

@@ -2,7 +2,7 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # A DOMAIN'S OWN DECLARED FACTS, PROJECTED AS PLAIN ENGLISH SENTENCES
+    # A domain's own declared facts, projected as plain english sentences
     # — one atomic, independently-checkable statement per fact, not a
     # flowing document (`Projections::Reference`/`DocsProjector` already
     # do that job well; this is a flat list a caller can iterate, diff,
@@ -10,27 +10,30 @@ module Hecks
     # a sanity check that the domain still says what someone thinks it
     # says).
     #
-    # NEVER INVENTS A SENTENCE FROM NOTHING — `DocsProjector`'s own
-    # discipline, held here too: a relationship's sentence is built
-    # MECHANICALLY from its own declared shape (holder, target,
-    # relationship kind — the same facts `Projections::Diagrams`'s own
-    # relationship_edge already reads), and an invariant's sentence IS
-    # the domain author's own `description`, capitalized and
-    # punctuated, never paraphrased. If a fact has no author-written
-    # description and no unambiguous mechanical phrasing, it doesn't
-    # get a sentence here — a wrong sentence is worse than a missing
-    # one.
+    # ## Never invents a sentence from nothing
     #
-    # REACHABLE THE SAME WAY EVERY PROJECTION ALREADY IS, no new facade
-    # wiring needed: `Pizzas.project(Projections::Statements)` —
-    # `Facade::Surface::Chapter#project`'s own comment already settled
+    # `DocsProjector`'s own discipline, held here too: a relationship's
+    # sentence is built mechanically from its own declared shape (holder,
+    # target, relationship kind — the same facts `Projections::Diagrams`'s
+    # own relationship_edge already reads), and an invariant's sentence is
+    # the domain author's own `description`, capitalized and punctuated,
+    # never paraphrased. If a fact has no author-written description and
+    # no unambiguous mechanical phrasing, it doesn't get a sentence here —
+    # a wrong sentence is worse than a missing one.
+    #
+    # ## Reachable like any projection
+    #
+    # No new facade wiring needed: `Pizzas.project(Projections::Statements)`
+    # — `Facade::Surface::Chapter#project`'s own comment already settled
     # this ("anything genuinely needing the graph is a projector, and a
     # projector is given it"). `bin/statements` is a thin, optional
     # convenience for reaching the same call from a shell.
     #
-    # MVP SCOPE: "has many"/"has a"/"belongs to"/"references" sentences
-    # for every list or relationship attribute, and every invariant's
-    # own description (aggregate-level and every nested value object's),
+    # ## MVP scope
+    #
+    # "has many"/"has a"/"belongs to"/"references" sentences for every
+    # list or relationship attribute, and every invariant's own
+    # description (aggregate-level and every nested value object's),
     # verbatim. Lifecycle transitions and command given/ensures read the
     # same way and are the natural next sentences — not built yet.
     module Statements
@@ -40,17 +43,35 @@ module Hecks
 
       module_function
 
+      # Projects every reachable fact in the chapter into its flat sentence list.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being projected
+      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @return [Array<String>] one sentence per attribute relationship and invariant,
+      #   in holder order
       def call(bluebook:, options: {})
         holders(bluebook).flat_map { |holder| statements_for(holder) }
       end
 
+      # Every construct that can carry its own attributes and invariants — an
+      # aggregate and each of its entities.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter being walked
+      # @return [Array<Bluebook::Aggregate, Bluebook::Entity>] every aggregate followed
+      #   by its own entities, in declaration order
       def holders(bluebook) = bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
 
+      # All of one holder's sentences: its attribute relationships, then its invariants.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct being
+      #   projected
+      # @return [Array<String>] the holder's sentences
       def statements_for(holder)
         attribute_statements(holder) + invariant_statements(holder)
       end
 
-      # "MANY" READS THE SAME WAY REGARDLESS OF WHAT'S BEHIND IT — a
+      # "MANY" reads the same way regardless of what's behind it — a
       # `has_many` relationship to another aggregate and a plain
       # `list_of(Topping)` value-object attribute are the same idea to
       # someone reading the domain in English ("an Order has many
@@ -60,10 +81,24 @@ module Hecks
       # name, because the field's own name is what the domain author
       # actually chose to call the collection — "toppings", not
       # "Topping".
+      # Projects every one of a holder's attributes that says something in plain
+      # English — a list, or a named relationship.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   attributes are being read
+      # @return [Array<String>] one sentence per list or relationship attribute; a
+      #   plain scalar attribute contributes none
       def attribute_statements(holder)
         holder.attributes.filter_map { |attribute| attribute_statement(holder, attribute) }
       end
 
+      # Projects one attribute's relationship, if it has one worth stating.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the attribute's owning
+      #   construct, named as the sentence's subject
+      # @param attribute [Bluebook::Attribute] the attribute being projected
+      # @return [String, nil] the sentence, or `nil` if `attribute` is neither a list
+      #   nor a `has_one`/`belongs_to`/`reference_to` relationship
       def attribute_statement(holder, attribute)
         subject = "#{article(holder.hecks_name)} #{holder.hecks_name}"
         return "#{subject} has many #{attribute.name}." if attribute.list?
@@ -77,29 +112,41 @@ module Hecks
         end
       end
 
-      # "AN ACCOUNT", NOT "A ACCOUNT" — every subject/object noun here is
+      # "An account", not "A ACCOUNT" — every subject/object noun here is
       # a bare construct name (`ATMCard`, `ExternalTransfer`, `Account`),
       # never free text, so the ordinary "starts with a vowel LETTER"
       # heuristic is safe: this language's own naming never produces the
       # English exceptions that heuristic gets wrong (an "hour", a
       # "university") because a construct name is always spelled as a
       # plain word, never an abbreviation read letter-by-letter or a
-      # word starting with a consonant LETTER but a vowel SOUND.
+      # word starting with a consonant letter but a vowel sound.
+      #
+      # @param word [String] a construct name to prefix
+      # @return [String] `"An"` if `word` starts with a vowel letter, `"A"` otherwise
       def article(word) = word.to_s.match?(/\A[AEIOUaeiou]/) ? "An" : "A"
 
-      # INVARIANTS LIVE IN TWO PLACES — directly on the holder (an
+      # Invariants live in two places — directly on the holder (an
       # aggregate-level rule, checked after every command) and on every
       # value object nested inside it — `DocsProjector#rules_of`'s own
       # `value_object_for` lookup is the precedent for walking both.
+      #
+      # @param holder [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   invariants, and whose value objects' invariants, are being read
+      # @return [Array<String>] one sentence per invariant, the holder's own first,
+      #   then each nested value object's
       def invariant_statements(holder)
         own = Array(holder.respond_to?(:invariants) ? holder.invariants : [])
         nested = Array(holder.respond_to?(:value_objects) ? holder.value_objects : []).flat_map(&:invariants)
         (own + nested).map { |invariant| invariant_statement(invariant) }
       end
 
-      # THE DOMAIN AUTHOR'S OWN WORDS, CAPITALIZED AND PUNCTUATED —
+      # The domain author's own words, capitalized and punctuated —
       # nothing else. `invariant("a pizza is named")` already reads as
       # a sentence; this is the entire transformation.
+      #
+      # @param invariant [Bluebook::Invariant] the invariant being projected
+      # @return [String] the invariant's `description`, capitalized, ending with `.`,
+      #   `!` or `?`
       def invariant_statement(invariant)
         text = invariant.description.to_s.strip
         text = "#{text[0].upcase}#{text[1..]}" if text[0]

data/lib/hecks/projections/vocabulary.rb

@@ -2,20 +2,20 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE CLOSED SETS, PROJECTED — lib/hecks/vocabulary.rb rendered
+    # **The closed sets, projected** — lib/hecks/vocabulary.rb rendered
     # from whichever chapter declares a `Vocabulary` aggregate, which in
     # practice is the language projecting its own tables.
     #
     #   Projector.call(:vocabulary, bluebook: <the Bluebook chapter>)
     #
-    # A PROJECTION RATHER THAN A BIN/ SCRIPT, and that correction is the
+    # A projection rather than a bin/ script, and that correction is the
     # point of it. This was first written as its own program with its own
     # call shape, beside `bin/project_parser_table`, `bin/reference` and
     # `bin/expression_projection` — four tools doing "canonical IR in,
     # external artifact out" four different ways, which is the exact
     # thing the projector registry exists to stop.
     #
-    # Reads the chapter's JUDGED IR, so what is written out is what the
+    # Reads the chapter's judged IR, so what is written out is what the
     # language actually holds rather than what a builder happened to
     # produce.
     module Vocabulary
@@ -24,10 +24,10 @@ module Hecks
       projects_as :vocabulary, declares: "Vocabulary"
 
       HEADER = <<~RUBY.freeze
-        # GENERATED — projected from the language's own Vocabulary aggregate
+        # Generated — projected from the language's own Vocabulary aggregate
         # (lib/hecks/language/bluebook/vocabulary.bluebook).
         #
-        # DO NOT EDIT. spec/vocabulary_table_spec.rb re-projects this in memory
+        # Do not edit. spec/vocabulary_table_spec.rb re-projects this in memory
         # and refuses a diff, so an edit here fails the ordinary suite.
         #
         # Plain data on purpose — no requires, no dependency on the model —
@@ -40,22 +40,39 @@ module Hecks
 
       # The projector protocol. `options` is unused: a vocabulary table
       # has nothing to vary.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to project
+      # @param options [Hash] unused; accepted to satisfy the registry's call shape
+      # @return [String] the rendered `lib/hecks/vocabulary.rb` source
       def call(bluebook:, options: {}) = render(bluebook)
 
-      # FULL ROWS, not just the first field of each.
+      # Full rows, not just the first field of each.
       #
-      # Most vocabularies ARE one-field lists and the field is the term.
+      # Most vocabularies are one-field lists and the field is the term.
       # Several are not: `Comparison` declares the algebra each operator
       # computes with, `RefusalTemplate` an error plus its key and text.
       # Taking the first field of those produced a list of thirty-nine
       # duplicated error names — well-formed and meaningless. So rows are
       # carried whole, and the terms are derived from them.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to read
+      # @return [Hash{String => Array<Hash{String => String}>}] each closed set's name,
+      #   mapped to its member rows with every field stringified
       def tables(bluebook)
         bluebook.aggregate("Vocabulary").value_objects.to_h do |vo|
           [vo.hecks_name, vo.members.map { |row| row.to_h.transform_keys(&:to_s).transform_values(&:to_s) }]
         end
       end
 
+      # Renders `lib/hecks/vocabulary.rb`'s full source: the frozen `TABLES`
+      # and `TERMS` constants and the `fetch`/`rows`/`symbols`/`names` reader
+      # methods, built from `bluebook`'s declared closed sets.
+      #
+      # @param bluebook [Bluebook::Behaviour::Chapter] the chapter declaring the
+      #   Vocabulary aggregate to render
+      # @return [String] the generated Ruby source, ready to write to disk
       def render(bluebook)
         rows = tables(bluebook).sort_by(&:first).map do |name, members|
           "      #{name.inspect} => [\n#{members.map { |row| "        #{row.inspect}.freeze" }.join(",\n")}\n      ].freeze"
@@ -69,8 +86,8 @@ module Hecks
           #{rows.join(",\n")}
               }.freeze
 
-              # THE TERMS — the first field of each row, which for a
-              # one-field vocabulary is the whole of it. Derived ONCE and
+              # The terms — the first field of each row, which for a
+              # one-field vocabulary is the whole of it. Derived once and
               # frozen rather than mapped per call: these are constant
               # tables, and a constant that allocates a new array every
               # time it is read is not one.

data/lib/hecks/projections.rb

@@ -1,7 +1,7 @@
 require_relative "projector"
 
 module Hecks
-  # THE TARGETS A DOMAIN CAN BE PROJECTED INTO, as constants rather than
+  # The targets a domain can be projected into, as constants rather than
   # bare symbols — `Pizzas.project(Projections::OIDC)`.
   #
   # A constant is worth the namespace for two reasons a Symbol cannot
@@ -10,9 +10,9 @@ module Hecks
   # carry its own documentation and defaults.
   #
   # Namespaced rather than top-level because `IR` is already taken —
-  # `Hecks::Bluebook` is the MODEL (`Bluebook::Command`, and the
+  # `Hecks::Bluebook` is the model (`Bluebook::Command`, and the
   # chapter class itself).
-  # `Projections::IR` is the projection OF that model, a different thing
+  # `Projections::IR` is the projection of that model, a different thing
   # that would be genuinely confusing under the same bare name.
   #
   # `include Hecks::Projections` gets the short spelling where the
@@ -26,6 +26,8 @@ require_relative "projections/shape"
 require_relative "projections/oidc"
 require_relative "projections/vocabulary"
 require_relative "projections/parser_table"
+require_relative "projections/bootstrap_table"
+require_relative "projections/rust_vocabulary"
 require_relative "projections/reference"
 require_relative "projections/model"
 require_relative "projections/diagrams"