hecks 0.2.0 → 0.3.0

data/lib/hecks/bluebook/dsl/const_shim.rb

@@ -0,0 +1,81 @@
+module Hecks
+  module Bluebook
+    module DSL
+      module ConstShim
+        class << self
+          attr_accessor :resolver
+
+          def with(resolver)
+            previous  = @resolver
+            @resolver = resolver
+            yield
+          ensure
+            @resolver = previous
+          end
+
+          def active? = !@resolver.nil?
+        end
+
+        # THE SCOPED-CONSTANT BRIDGE (ADR 0025, docs/dsl-work-slices.md's
+        # S0b) — a Symbol cannot answer `::`, so `Account::Debit` and
+        # `admits: Account::LedgerDirection` could never resolve past
+        # their FIRST segment while `Account` returned a bare Symbol
+        # (`resolver = ->(const) { const }`, bluebook_builder.rb's own
+        # comment on why that was right for a BARE name): Ruby's `::`
+        # operator raises `TypeError` on the returned value before any
+        # DSL code runs at all, unless that value is itself a Module.
+        #
+        # A REAL `Module` subclass, not a decorated Symbol, for exactly
+        # that reason — nothing else answers `::`. Every existing
+        # consumer keeps working duck-typed, not because nothing
+        # changed: `Attribute#spell`'s `type.is_a?(Module)` branch now
+        # fires where it used to fall to `type.to_s`, and
+        # `Naming.demodulise` (`path.split("::").last`) gives the
+        # IDENTICAL string either way for a single segment — the two
+        # branches were already equivalent for a name with no `::` in
+        # it, which is every bareword before this.
+        class ScopedConstant < Module
+          def self.for(path) = new(path.to_s)
+
+          def initialize(path)
+            super()
+            @path = path
+          end
+
+          # ONE MORE SEGMENT, the same way an unresolved const anywhere
+          # else does — `Account::Debit::Anything` keeps chaining rather
+          # than refusing, since nothing here knows how deep a reference
+          # is meant to go; the DSL keyword that finally reads `.to_s`
+          # is the one place that does.
+          def const_missing(name) = ScopedConstant.for("#{@path}::#{name}")
+
+          def to_s     = @path
+          def to_sym   = @path.to_sym
+          def inspect  = @path
+          def hecks_path = @path
+
+          def ==(other) = other.is_a?(ScopedConstant) ? @path == other.hecks_path : @path.to_sym == other
+          alias eql? ==
+          def hash = @path.hash
+        end
+
+        # A SCOPED NAME IS WRITTEN AS TEXT, NOT AS A CONSTANT PATH — see the
+        # note on `admits:` in AttributeCollector. A resolver returning a
+        # Module (so that `Vocabulary::QueryComparator` reaches a second
+        # `const_missing`) was tried and cannot be made to hold : `Facade::
+        # Surface` installs EVERY aggregate name as a top-level constant, so
+        # once any facade is built, `Vocabulary` resolves to that real module
+        # and never reaches this hook at all. A spelling that works only
+        # before a facade exists is worse than one that always works.
+        module Hook
+          def const_missing(name)
+            resolver = ConstShim.resolver
+            resolver ? resolver.call(name) : super
+          end
+        end
+      end
+    end
+  end
+end
+
+Object.singleton_class.prepend(Hecks::Bluebook::DSL::ConstShim::Hook)

data/lib/hecks/bluebook/dsl/domain_port_builder.rb

@@ -0,0 +1,79 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class DomainPortBuilder
+        GRAMMAR_CONTEXT = "DomainPort"
+
+        include WordGate
+
+        def initialize(name, owner: nil)
+          @name       = name
+          @owner      = owner
+          @operations = []
+        end
+
+        # WHAT THE OUTSIDE TELLS US — an external fact arriving, translated
+        # into this domain's own word for it. Spelled `operation` before it
+        # had a twin, and `operation` still works: the corpus is full of it,
+        # and renaming a word costs every chapter that uses it for no gain a
+        # reader can feel.
+        #
+        # RENAMED FROM `tells` — item #13's full metaprogrammed dispatch
+        # (slice 4c). `operation`/`tells` are TWO separate Keyword rows
+        # (a word admitting two forms) that both name `calls: "tells_impl"`
+        # — the routing between the two spellings now lives in the table,
+        # not in a Ruby `alias`. Not bootstrap-reachable (checked
+        # directly), so no BOOTSTRAP_CALLS_FALLBACK entry needed.
+        def tells_impl(name, to: nil, &block)
+          @operations << PortOperationBuilder.build(name, to: to, owner: @owner, direction: :inbound, &block)
+        end
+
+        # WHAT WE ASK OF THE OUTSIDE — the direction this language did not
+        # have. Before this, a domain could be CALLED by an adapter and never
+        # call one. An `asks` is dispatched like any other port operation, so
+        # a `policy` can trigger it off an event, and it comes back as one of
+        # the two events it named — which is what makes the outside world
+        # something the model can reason about rather than a place exceptions
+        # come from.
+        #
+        # RENAMED FROM `asks` — item #13's full metaprogrammed dispatch
+        # (slice 4c), same reasoning as tells_impl above.
+        def asks_impl(name, to: nil, &block)
+          @operations << PortOperationBuilder.build(name, to: to, owner: @owner, direction: :outbound, &block)
+        end
+
+        # THE DRIVEN HALF OF THE SAME WORD. `operation`/`emits` translates an
+        # inbound fact into this domain's own event vocabulary — there is no
+        # channel back to a caller beyond the events it emits. `verb` is the
+        # opposite direction: the domain calling OUT to a swappable adapter
+        # and getting a real value back (a checkout URL, a fetched document),
+        # exactly what `Hecks.port "name" do verb "x" end` already builds —
+        # this is that same `Port`, reached from the same `port` call
+        # `operation` already lives under, so a project's own resource ports
+        # read next to their binding instead of in a separate file. One port,
+        # one shape or the other — never both.
+        # `verb` — item #13's full metaprogrammed dispatch, slice 1
+        # (whole-project table-unification survey): a bare, kind-driven
+        # coerce-and-assign with nothing else, now executed by
+        # `GenericDispatch`.
+
+        def build
+          raise Malformed, "#{@name} declares both a verb and operations — a port is one or the other, not both" if @verb && !@operations.empty?
+
+          return Port.new(name: @name, verb: @verb, signal: :reply) if @verb
+
+          raise Malformed, "#{@name} declares no verb and no operations" if @operations.empty?
+
+          DomainPort.new(name: @name, operations: @operations)
+        end
+
+        def self.build(name, owner: nil, &block)
+          builder = new(name, owner: owner)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/entity_builder.rb

@@ -0,0 +1,305 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class EntityBuilder
+        GRAMMAR_CONTEXT = "Entity"
+
+        include AttributeCollector
+        include IdentityDeclaration
+        include RuleReference
+        include WordGate
+
+        def initialize(name, owner_value_objects: [], owner_named_givens: {},
+                       identity_name_prefix: nil, identity_value_object_installer: nil)
+          @name         = name
+          @commands     = []
+          @queries      = []
+          @entities     = []
+          @named_givens = {}
+          @invariants   = []
+          @owner_value_objects = owner_value_objects
+          @identity_name_prefix = identity_name_prefix || Naming.demodulise(name)
+          @identity_value_object_installer = identity_value_object_installer
+          # THE AGGREGATE-WIDE cross-entity given pool — ONE hash, the
+          # SAME object, threaded unchanged through every piece nested
+          # under one aggregate however deep (the identical shape
+          # `@owner_value_objects` already threads — see this class'
+          # own `entity` comment). `given`'s own block form writes
+          # through to it; a SIBLING piece's bare command-level
+          # reference reads from it via `CommandBuilder#
+          # reference_named_given`.
+          @owner_named_givens = owner_named_givens
+          # DEFERRED CONSTRUCTION — see `AggregateBuilder#drain_pending!`'s
+          # own comment; the identical mechanism, one level down, so a
+          # nested piece's own commands (Dispatch inside Handler) see
+          # every SIBLING entity/command/query this piece goes on to
+          # declare, not just whatever came before it textually.
+          @pending_entities = []
+          @pending_commands = []
+          @pending_queries  = []
+        end
+
+        def description(value) = @description = value
+
+        # THE SAME FIELD AggregateBuilder's OWN reference_to BUILDS — a
+        # piece can hold a reference to another root exactly the way its
+        # own head can (Card.assignee_id, a Team's own id), just never
+        # to another PIECE, since there's no cross-piece addressing
+        # anywhere in this language to resolve one against.
+        # RENAMED FROM `reference_to` — item #13's full metaprogrammed
+        # dispatch (slice 4b). Bootstrap-reachable, in
+        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        def reference_to_impl(type, as: nil, optional: false)
+          target = Naming.demodulise(type)
+          relationship_attribute(target, :reference_to,
+                                 as || default_reference_name(target), optional: optional)
+        end
+
+        # has_many_impl/has_one_impl are DSL declaration keywords a domain
+        # author writes as bare has_many/has_one (matching belongs_to_impl
+        # alongside them) — not real predicates, so renaming to many?/one?
+        # per Naming/PredicatePrefix would break every bluebook that
+        # declares one. New on Entity (Wave 6, identity-and-relationships
+        # arc) — pieces never had relationship words before; named
+        # `*_impl` to match AggregateBuilder's own siblings, item #13's
+        # full metaprogrammed dispatch convention.
+        # rubocop:disable Naming/PredicatePrefix
+        def has_many_impl(type, as: nil, **options)
+          unless options.empty?
+            raise Malformed, "#{@name}.has_many takes no #{options.keys.first}: — an empty list already means none"
+          end
+
+          plural = Naming.demodulise(type)
+          relationship_attribute(Naming.singularize(plural), :has_many,
+                                 as || Naming.snake(plural).to_sym, list: true)
+        end
+
+        def has_one_impl(type, as: nil, optional: false)
+          target = Naming.demodulise(type)
+          relationship_attribute(target, :has_one, as || Naming.snake(target).to_sym, optional: optional)
+        end
+        # rubocop:enable Naming/PredicatePrefix
+
+        def belongs_to_impl(type, as: nil, optional: false)
+          target = Naming.demodulise(type)
+          relationship_attribute(target, :belongs_to, as || Naming.snake(target).to_sym, optional: optional)
+        end
+
+        # A PIECE is known by a field, not by a whole value object.
+        # `identified_by :sequence` names the SCALAR inside it, which is
+        # what an id actually is — a LedgerEntry is entry 3, not entry
+        # {"value":3}. `identified_by` itself is AttributeCollector's own
+        # shared method (S9) — the two constructs cannot drift apart in
+        # how they spell an identity, including composite
+        # (`identified_by :branch_code, :box_number`), which a piece may
+        # declare for the same reason a head may.
+
+        # `from:` — see `AggregateBuilder#command`'s own comment; the
+        # SAME guard, checked against this PIECE's own lifecycle field
+        # (S10, ADR 0025 — a piece's own state machine is checkable the
+        # same way a head's is).
+        # RENAMED FROM `command`/`query`/`entity`/`lifecycle` (all below)
+        # — item #13's full metaprogrammed dispatch (slice 4c), same
+        # reasoning as AggregateBuilder's own siblings: bootstrap-
+        # reachable, in BOOTSTRAP_CALLS_FALLBACK.
+        def command_impl(name, from: nil, &block)
+          @pending_commands << [name, from, block]
+        end
+
+        def query_impl(name, &block)
+          @pending_queries << [name, block]
+        end
+
+        # S17, ADR 0026 — A PIECE NESTED INSIDE A PIECE. "A `Dispatch`
+        # [has] no life outside its `Handler`" (the ADR's own words) —
+        # the same reason `Member` nests inside `ValueObject`, one level
+        # further in. `owner_value_objects` passes straight through
+        # unchanged, not re-derived from this entity's own attributes —
+        # a piece mints no value objects of its own at any depth, so a
+        # NESTED piece's bare `identified_by :field` still resolves
+        # against the SAME root aggregate's value objects an outer
+        # piece's already does (`AggregateBuilder#entity`'s own comment
+        # names this pool ; there is exactly one of them, however deep
+        # the nesting goes).
+        def entity_impl(name, &block)
+          @pending_entities << [name, block]
+        end
+
+        def lifecycle_impl(field, default:, &block)
+          @lifecycle = LifecycleBuilder.build(field, default: default, &block)
+        end
+
+        # A PRECONDITION SHARED ACROSS THIS PIECE'S OWN COMMANDS, DECLARED
+        # ONCE — the same move `AggregateBuilder#given` already makes,
+        # one level down. Real, live redundancy this closes: banking's
+        # own `LedgerEntry.Amend`/`LedgerEntry.Reverse` each repeated
+        # `given("customer is active") { parent.customer.status ==
+        # "active" }` and `given("account is open") { parent.status ==
+        # "open" }`, byte for byte, because a piece had no way to declare
+        # either once and reference it back — only the AGGREGATE could.
+        # DECLARE BEFORE THE COMMANDS THAT REFERENCE IT, the same
+        # ordering `AggregateBuilder#given`'s own comment names — though
+        # since ADR 0028, `command` only queues a descriptor and actually
+        # builds at `#drain_pending!` time, well after this whole block
+        # (including every `given` in it) has already run, so textual
+        # order within the block no longer actually matters here; named
+        # for the reader anyway, since `given`'s own resolution logic
+        # (`CommandBuilder#reference_named_given`) still reads whatever
+        # `@named_givens` holds AT THE COMMAND'S OWN BUILD TIME, not by
+        # magic.
+        # RENAMED FROM `given` — item #13's full metaprogrammed dispatch
+        # (slice 4b), same reasoning as reference_to_impl above.
+        def given_impl(description, &predicate)
+          named = build_rule(Given, description, predicate, owner_name: @name, word: "given",
+                              extraction_failure: "its source could not be read, so no other runtime could ever evaluate it")
+          @named_givens[description] = named
+          # WRITE-THROUGH, first-declared-wins (`||=`) — a SECOND piece
+          # under the same aggregate independently declaring the exact
+          # same description stays purely local to itself (no silent
+          # overwrite of whatever the first piece already shared;
+          # real, live case a fuzzer or a future codemod could easily
+          # surface: two pieces phrasing an UNRELATED rule identically
+          # by coincidence, same as an aggregate-level given already
+          # tolerates today).
+          @owner_named_givens[description] ||= named
+        end
+
+        # A PIECE'S OWN SHAPE RULE (S10, ADR 0025's own "Rules" shape,
+        # one level down from `ValueObjectBuilder#invariant`, whose
+        # extraction/error pattern this mirrors) — checked against
+        # EVERY INSTANCE of this piece the aggregate holds, not once
+        # against the aggregate's own flat state
+        # (`Admissibility#enforce_invariants`'s own recursive walk).
+        # No reference-by-name form (unlike `given`) — no known corpus
+        # need for a piece's own invariant to be shared with a SIBLING
+        # piece yet; if that need shows up, it is `given`'s own
+        # cross-entity write-through pattern to extend, not a reason to
+        # invent a second one here speculatively.
+        # RENAMED FROM `invariant` — item #13's full metaprogrammed
+        # dispatch (slice 4b), same reasoning as given_impl above.
+        def invariant_impl(description, &predicate)
+          @invariants << build_rule(Invariant, description, predicate, owner_name: @name, word: "invariant",
+                                     extraction_failure: "it would be a rule the IR cannot carry")
+        end
+
+        def build
+          drain_pending!
+          resolve_pending_identity!
+          seal_lifecycle_guards
+          install_closed_sets!
+          Entity.declare(
+            name:          @name,
+            description:   @description,
+            identified_by: @identity_paths,
+            attributes:    attributes,
+            commands:      @commands,
+            queries:       @queries,
+            entities:      @entities,
+            preconditions: @named_givens.values,
+            invariants:    @invariants,
+            lifecycle:     @lifecycle
+          )
+        end
+
+        def self.build(name, owner_value_objects: [], owner_named_givens: {},
+                       identity_name_prefix: nil, identity_value_object_installer: nil, &block)
+          builder = new(name, owner_value_objects: owner_value_objects, owner_named_givens: owner_named_givens,
+                              identity_name_prefix: identity_name_prefix,
+                              identity_value_object_installer: identity_value_object_installer)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+
+        private
+
+        # A PIECE'S OWN `one_of` LANDS ON ITS AGGREGATE. A type-position
+        # `one_of("never_moved", "moved")` on an entity attribute
+        # synthesizes a closed-set value object — and until this, that
+        # object was built and then DROPPED: `Entity.declare` carries no
+        # value objects, so the synthesized set existed nowhere in the
+        # finished graph. The attribute stayed typed "Moved" with nothing
+        # to resolve it: runtime admission had no closed set to enforce
+        # (the one_of was decorative), and the fuzzer's ValueGenerator
+        # crashed every run on the first domain to declare one — a chess
+        # King/Rook's own castling flag — with `does not know primitive
+        # type "Moved"`. Installed through the SAME hook an entity's own
+        # identity value object already rides to the aggregate
+        # (`identity_value_object_installer`, threaded unchanged through
+        # nested pieces). Two sibling pieces synthesizing the same set
+        # (King's and Rook's own `moved`) install it once; the same NAME
+        # with a DIFFERENT member list is refused as the collision it is,
+        # never first-wins silently.
+        def install_closed_sets!
+          return unless @identity_value_object_installer
+
+          closed_sets.each do |value_object|
+            existing = @owner_value_objects.find { |candidate| candidate.hecks_name == value_object.hecks_name }
+            if existing
+              next if existing.to_h == value_object.to_h
+
+              raise Malformed,
+                    "#{@name}'s one_of synthesizes #{value_object.hecks_name.inspect}, but the aggregate already " \
+                    "holds a different #{value_object.hecks_name.inspect} — name the closed set's field differently"
+            end
+
+            @identity_value_object_installer.call(value_object)
+          end
+        end
+
+        # See `AggregateBuilder#drain_pending!`'s own comment — the
+        # identical mechanism, one level down. Entities first and fully
+        # built (so a nested command's own `append:` resolution can read
+        # a sibling piece's `.attributes`), then commands, then queries.
+        def drain_pending!
+          @entities = @pending_entities.map do |name, block|
+            EntityBuilder.build(name, owner_value_objects:             @owner_value_objects,
+                                      owner_named_givens:              @owner_named_givens,
+                                      identity_name_prefix:            "#{@identity_name_prefix}#{Naming.demodulise(name)}",
+                                      identity_value_object_installer: @identity_value_object_installer,
+                                &block)
+          end
+
+          @commands = @pending_commands.map do |name, from, block|
+            CommandBuilder.build(name, owner: @name, from: from, named_givens: @named_givens,
+                                        owner_attributes: attributes,
+                                        owner_constructs: @owner_value_objects + @entities,
+                                        entity_shared_givens: @owner_named_givens, &block)
+          end
+
+          @queries = @pending_queries.map do |name, block|
+            QueryBuilder.build(name, owner_attributes: attributes, &block)
+          end
+        end
+
+        # See `AggregateBuilder#seal_lifecycle_guards`'s own comment —
+        # the identical check, one level down.
+        def seal_lifecycle_guards
+          return if @lifecycle
+
+          @commands.each do |command|
+            next unless command.from
+
+            raise Malformed,
+                  "#{@name}.#{command.hecks_name} guards from: #{Array(command.from).inspect}, but " \
+                  "#{@name} declares no lifecycle — from: checks a lifecycle field, and there is " \
+                  "none here to check"
+          end
+        end
+
+        # `identified_by`'s own resolution pool (AttributeCollector#resolve_
+        # pending_identity!'s hook, S9) — a piece mints no value objects of
+        # its own, so a bare field's own type resolves against its OWNER
+        # aggregate's, passed in at declaration (`AggregateBuilder#entity`).
+        def identity_pool = @owner_value_objects
+
+        def identity_value_object_name = "#{@identity_name_prefix}Identity"
+
+        def install_identity_value_object!(value_object)
+          @identity_value_object_installer&.call(value_object)
+          @owner_value_objects << value_object unless @owner_value_objects.include?(value_object)
+        end
+      end
+    end
+  end
+end