hecks 0.2.0 → 1.0.0

data/lib/hecks/projections/statements.rb

@@ -0,0 +1,110 @@
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # 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,
+    # or hand to something else entirely — a review, a test-plan seed,
+    # 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.
+    #
+    # 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
+    # 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),
+    # verbatim. Lifecycle transitions and command given/ensures read the
+    # same way and are the natural next sentences — not built yet.
+    module Statements
+      extend Hecks::Projector::Target
+
+      projects_as :statements
+
+      module_function
+
+      def call(bluebook:, options: {})
+        holders(bluebook).flat_map { |holder| statements_for(holder) }
+      end
+
+      def holders(bluebook) = bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
+
+      def statements_for(holder)
+        attribute_statements(holder) + invariant_statements(holder)
+      end
+
+      # "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
+      # toppings" is true either way), even though they're two
+      # different IR shapes (a `Reference` versus an ordinary type).
+      # `attribute.name` carries the noun, not the target's own class
+      # name, because the field's own name is what the domain author
+      # actually chose to call the collection — "toppings", not
+      # "Topping".
+      def attribute_statements(holder)
+        holder.attributes.filter_map { |attribute| attribute_statement(holder, attribute) }
+      end
+
+      def attribute_statement(holder, attribute)
+        subject = "#{article(holder.hecks_name)} #{holder.hecks_name}"
+        return "#{subject} has many #{attribute.name}." if attribute.list?
+
+        target = attribute.relationship && attribute.type.target_name
+        target_phrase = target && "#{article(target).downcase} #{target}"
+        case attribute.relationship
+        when "has_one"      then "#{subject} has #{target_phrase}."
+        when "belongs_to"   then "#{subject} belongs to #{target_phrase}."
+        when "reference_to" then "#{subject} references #{target_phrase}."
+        end
+      end
+
+      # "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.
+      def article(word) = word.to_s.match?(/\A[AEIOUaeiou]/) ? "An" : "A"
+
+      # 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.
+      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 —
+      # nothing else. `invariant("a pizza is named")` already reads as
+      # a sentence; this is the entire transformation.
+      def invariant_statement(invariant)
+        text = invariant.description.to_s.strip
+        text = "#{text[0].upcase}#{text[1..]}" if text[0]
+        text.end_with?(".", "!", "?") ? text : "#{text}."
+      end
+    end
+  end
+end

data/lib/hecks/projections/vocabulary.rb

@@ -0,0 +1,100 @@
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # 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
+    # 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
+    # language actually holds rather than what a builder happened to
+    # produce.
+    module Vocabulary
+      extend Projector::Target
+
+      projects_as :vocabulary, declares: "Vocabulary"
+
+      HEADER = <<~RUBY.freeze
+        # 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
+        # and refuses a diff, so an edit here fails the ordinary suite.
+        #
+        # Plain data on purpose — no requires, no dependency on the model —
+        # because several of these sets are read while a bluebook is still
+        # being parsed. A table that needed the framework to load could not
+        # be the table the framework loads with.
+      RUBY
+
+      module_function
+
+      # The projector protocol. `options` is unused: a vocabulary table
+      # has nothing to vary.
+      def call(bluebook:, options: {}) = render(bluebook)
+
+      # FULL ROWS, not just the first field of each.
+      #
+      # 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.
+      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
+
+      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"
+        end
+
+        <<~RUBY
+          #{HEADER}
+          module Hecks
+            module Vocabulary
+              TABLES = {
+          #{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
+              # 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.
+              TERMS = TABLES.transform_values { |rows| rows.map { |row| row.values.first }.freeze }.freeze
+
+              module_function
+
+              # Refuses an unknown name rather than answering nil: a set
+              # the language does not declare is a typo, not an empty set.
+              def fetch(name) = TERMS.fetch(name)
+
+              # The rows whole, for the vocabularies that carry more than
+              # a term — Comparison's own algebra, RefusalTemplate's text.
+              def rows(name) = TABLES.fetch(name)
+
+              def symbols(name) = fetch(name).map(&:to_sym)
+
+              def names = TABLES.keys
+            end
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/hecks/projections.rb

@@ -0,0 +1,32 @@
+require_relative "projector"
+
+module Hecks
+  # 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
+  # give: a typo raises `NameError` at the call site instead of
+  # `UnknownProjector` at dispatch time, and each target has somewhere to
+  # 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
+  # chapter class itself).
+  # `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
+  # extra qualification is noise (`bin/` scripts, a console session).
+  module Projections
+  end
+end
+
+require_relative "projections/ir"
+require_relative "projections/shape"
+require_relative "projections/oidc"
+require_relative "projections/vocabulary"
+require_relative "projections/parser_table"
+require_relative "projections/reference"
+require_relative "projections/model"
+require_relative "projections/diagrams"
+require_relative "projections/statements"