hecks 0.2.0 → 0.3.0

data/lib/hecks/bluebook/assembly/aggregate_assembly.rb

@@ -0,0 +1,134 @@
+module Hecks
+  module Bluebook
+    class Assembly
+      # One head, built from its declaration.
+      #
+      # The fields come from the contract like every other construct's. What is here
+      # is the part no field table can say: which construct holds which, and how a
+      # head's references become able to resolve.
+      #
+      # It DECIDES NOTHING. Whether a declaration is admissible was settled on the
+      # way in, by the language.
+      class AggregateAssembly
+        def initialize(row)
+          @row = row
+        end
+
+        def aggregate
+          shapes   = Array(@row[:value_objects]).map { |shape| value_object(shape) }
+          commands = Array(@row[:commands]).map { |verb| Build.call("Command", verb) }
+          entities = Array(@row[:entities]).map { |piece| entity(piece) }
+          asks     = Array(@row[:queries]).map { |ask| Build.call("Query", ask) }
+
+          fields = Array(@row[:attributes]).map { |field| Marks.attribute(field) }
+
+          ir = Build.call(
+            "Aggregate", @row,
+            value_objects:     shapes,
+            commands:          commands,
+            entities:          entities,
+            queries:           asks,
+            lifecycle:         lifecycle_of(@row),
+            # A policy declared inside a head is HOISTED onto the chapter by the
+            # builder, and `Aggregate#to_h` never carried it — so the language does
+            # not record which head a chapter-level policy was written in. The
+            # chapter holds them all, which is what `PolicyInterpreter` reads.
+            policies:          [],
+            reference_targets: reference_targets(fields)
+          )
+
+          stamp_references(ir)
+          ir
+        end
+
+        private
+
+        # What this head points at with an aggregate-level `reference_to`. NOT the
+        # self-references its verbs carry — the first version read
+        # `commands.filter_map(&:references)` and gave Pizza two targets of "Pizza",
+        # its own verbs pointing at itself, where the builder recorded none. An
+        # aggregate-level `reference_to X` leaves a reference ATTRIBUTE behind, so
+        # the attributes are where the answer is.
+        def reference_targets(fields)
+          fields.select(&:reference?).map { |field| field.type.target_name }
+        end
+
+        def value_object(row)
+          Build.call("ValueObject", row)
+        end
+
+        # S17, ADR 0026 — RECURSES. "That is what `entity` is for, and
+        # `entity` is declared by the language and used zero times in it"
+        # — Dispatch, inside Handler, is the first use, so `row[:entities]`
+        # is built the same way `row` itself was reached: through this
+        # same method, one level deeper each time. Nothing here assumes
+        # it stops at one level of nesting.
+        def entity(row)
+          Build.call(
+            "Entity", row,
+            commands:  Array(row[:commands]).map { |verb| Build.call("Command", verb) },
+            queries:   Array(row[:queries]).map { |ask| Build.call("Query", ask) },
+            entities:  Array(row[:entities]).map { |piece| entity(piece) },
+            lifecycle: lifecycle_of(row)
+          )
+        end
+
+        # Every reference learns which head declares it, so it can reach the chapter
+        # and resolve. Deliberately across every list that can carry one — a
+        # reference the walk misses resolves to nil, and a nil target is SKIPPED
+        # rather than refused, so the guarantee would go quiet instead of red.
+        def stamp_references(ir)
+          lists = [ir.attributes, *ir.commands.map(&:attributes), *ir.queries.map(&:attributes)]
+          entity_reference_lists(ir.entities, lists)
+
+          lists.flatten.select(&:reference?).each { |field| field.type.declared_in = ir }
+        end
+
+        # S17, ADR 0026 — walks NESTED entities too (Dispatch, inside
+        # Handler), not only an aggregate's own direct ones.
+        def entity_reference_lists(entities, lists)
+          entities.each do |piece|
+            lists << piece.attributes
+            lists.concat(piece.commands.map(&:attributes))
+            lists.concat(piece.queries.map(&:attributes))
+            entity_reference_lists(piece.entities, lists)
+          end
+        end
+
+        # THREE LANGUAGE FIELDS, ONE IR OBJECT. `state_field`, `state_start` and
+        # `transitions` are separate declarations; the IR keeps one Lifecycle. The
+        # contract names them derived, and this is what derives them.
+        def lifecycle_of(row)
+          declared = row[:lifecycle]
+          return nil unless declared
+
+          Lifecycle.new(
+            field:       declared[:field],
+            default:     declared[:default],
+            transitions: transitions(Array(declared[:transitions]))
+          )
+        end
+
+        # A lifecycle holds [command, StateTransition] pairs and `to_h` expands one
+        # pair whose `from` is a list into several rows. Grouped back by command AND
+        # TARGET, because one declared pair has exactly one target and may have many
+        # froms — grouping by command alone would fuse two declarations that move the
+        # same verb to different states.
+        def transitions(rows)
+          rows.group_by { |move| [move[:command], move[:to_state]] }
+              .map do |(command, target), moves|
+                froms = moves.filter_map { |move| move[:from_state] }
+                [command.to_s, StateTransition.new(target: target, from: from_of(froms))]
+              end
+        end
+
+        def from_of(froms)
+          return nil         if froms.empty?
+          return froms.first if froms.size == 1
+
+          froms
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/assembly/build.rb

@@ -0,0 +1,48 @@
+module Hecks
+  module Bluebook
+    class Assembly
+      # ONE WAY TO BUILD A CONSTRUCT, for every construct.
+      #
+      # There used to be a method per category here — `value_object(row)`,
+      # `command(row)`, `policy(row)` — each one gathering the same keywords the
+      # contract already names. This reads the contract instead, so adding a field
+      # to the language and forgetting to assemble it is caught by the coverage gate
+      # rather than by nobody.
+      #
+      # `make` is the only branch, and it is a real one: a construct that became a
+      # class is `.declare`d, an instance is `.new`ed. That is the boundary
+      # `Query` sits on, and it is a fact about Ruby rather than about the
+      # domain.
+      module Build
+        module_function
+
+        def call(category, row, extra = {})
+          contract = Assembly.contract(category)
+          keywords = contract.fields.to_h { |keyword, (key, reader)| [keyword, read(reader, row[key])] }
+
+          holder(contract).public_send(contract.make, **keywords.merge(extra))
+        end
+
+        def holder(contract)
+          contract.holder or raise ArgumentError, "#{contract} holds nothing that can be built"
+        end
+
+        # A reader is a Marks method, a list of them, or one of three spellings that
+        # need no decoding at all.
+        def read(reader, value)
+          case reader
+          when :plain    then value
+          when :identity then value&.to_sym
+          when :flag     then value ? true : false
+          when Array
+            # [:each, reader] maps a list ; [:option, name] reads one named option,
+            # which needs its name as well as its value.
+            reader.first == :each ? Array(value).map { |held| Marks.public_send(reader.last, held) }
+                                  : Marks.option(reader.last, value)
+          else Marks.public_send(reader, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/assembly/contract.rb

@@ -0,0 +1,112 @@
+module Hecks
+  module Bluebook
+    class Assembly
+      # WHAT A CONSTRUCT NEEDS THAT THE LANGUAGE CANNOT SAY, and how a claim that a
+      # field needs no assembling is CHECKED.
+      #
+      # `derived:` used to be a list of names, and a list of names is a promise with
+      # nobody holding it. The coverage gate only asked whether a field was accounted
+      # for — so writing `derived: %i[version]` would have satisfied it while dropping
+      # a chapter's version in silence, which is the exact shape of every defect this
+      # arc has found. Naming a field derived is a CLAIM, and a claim needs a kind:
+      #
+      #   :parent            the containment tree supplies it — a `*_id`, or one of
+      #                      the named pointers below. Checked against the name.
+      #   :children          it is assembled as child constructs. Checked against the
+      #                      language: a category must exist whose parent is this one.
+      #   [:computed, :m]    the holder works it out. Checked: it must answer to `m`.
+      #   [:folded, keys]    several language fields are one thing in the IR, or one
+      #                      is spread across several. Checked: every key must appear
+      #                      in a real reconstructed declaration.
+      #   :elsewhere         not a fact about this construct at all. Allow-listed one
+      #                      by one, because it is the kind with no other check.
+      #
+      # Every one of those can FAIL. That is the whole difference.
+      Contract = Struct.new(:holder, :make, :fields, :derived, :rows, :reads, keyword_init: true) do
+        # How a declaration key is read back off a ROW. Absent means the default —
+        # `text(row[key])`, a single cell — which is most of them ; present names the
+        # shape, because a list needs a reader per element and a folded field is
+        # gathered rather than fetched. Same pattern as `rows`, in the other
+        # direction: declare the exceptions, default the rest.
+        def reader(key) = Hash(reads)[key.to_sym]
+
+        # How an appendable LIST becomes rows the walk can offer. A list absent from
+        # here reads straight off the node ; one that is present names the shaper,
+        # because the IR keeps a shape the language does not — a transition whose
+        # `from` is a list is several rows, an append binds several fields at once,
+        # an open map is one row per entry.
+        def shaper(list) = Hash(rows)[list.to_sym]
+
+        def declares?(field) = fields.key?(field) || derived.key?(field)
+
+        def kind_of(field) = derived[field]
+
+        # WHERE A FOLDED FIELD ACTUALLY LIVES, as [object, member].
+        #
+        # `[:folded, :lifecycle, :field]` says the language's `state_field` is the
+        # `field` of the IR's one Lifecycle. That is the same fact `Readings` used to
+        # state a second time as `node.lifecycle&.field` — so saying it once here
+        # drives BOTH directions: the walk reads the member on the way in, and the
+        # reconstruction gathers the members back into the object on the way out.
+        #
+        # A nil member means the fold has no single member to name — `rows` is a
+        # count of what `closed_set` and `members` hold between them, and `options`
+        # spreads across eight keys. Those keep their own code, and the gate still
+        # checks the object they name is real.
+        def folded(field)
+          kind = derived[field]
+          return nil unless kind.is_a?(Array) && kind.first == :folded
+
+          [kind[1], kind[2]]
+        end
+
+        # COMPUTED means worked out, not merely answerable.
+        #
+        # Asking only whether the holder responds was too weak, and measurably so:
+        # `[:computed, :version]` passed, because `Bluebook` does answer to
+        # `version` — it just answers with what the constructor was handed. A field
+        # the constructor TAKES is stored, and calling it computed is how a chapter's
+        # version would have gone missing while the gate said yes.
+        #
+        # So a computed field is one the holder answers AND the constructor does not
+        # accept. `query_name` qualifies (`Naming.snake(name)`) ; `version` cannot.
+        def computes?(method)
+          return false unless holder
+          return false unless answers?(method)
+
+          !accepts?(method)
+        end
+
+        def answers?(method)
+          make == :declare ? holder.respond_to?(method) : holder.instance_methods.include?(method)
+        end
+
+        def accepts?(keyword)
+          builder = make == :declare ? holder.method(:declare) : holder.instance_method(:initialize)
+
+          builder.parameters.any? { |kind, name| %i[key keyreq].include?(kind) && name == keyword }
+        end
+      end
+
+      # The fields that hold a parent's id without being spelled `*_id`. An entity is
+      # declared in an aggregate, a member on a value object, a dispatch inside a
+      # handler, and each names its parent with a word rather than a suffix.
+      PARENT_POINTERS = %i[owner shape handler].freeze
+
+      # The only fields allowed to claim they describe something other than the
+      # construct they hang off, each with the reason spelled out.
+      #
+      #   normalisations   the canonical-form table belongs to the expression grammar.
+      #                    A chapter's rules are canonicalised on the way in, so the
+      #                    language models the table — but no chapter STORES one, and
+      #                    `Bluebook#to_h` splices it in from Expression.
+      ELSEWHERE = {
+        Bluebook: %i[normalisations]
+      }.freeze
+
+      def self.elsewhere?(category, field)
+        Array(ELSEWHERE[category.to_sym]).include?(field)
+      end
+    end
+  end
+end