hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,221 @@
+require_relative "generic_dispatch"
+module Hecks
+  module Bluebook
+    module DSL
+      # THE RUBY-SIDE `word_gate` (`rust/parser/src/parse/mod.rs`'s own,
+      # read there first — this is the same job, one level up: Rust's own
+      # gate refuses a mistyped/inadmissible WORD directly, at the
+      # moment it reads a line of `.bluebook` SOURCE TEXT, before any
+      # per-construct parsing runs. Ruby never lexes source text — a
+      # `.bluebook` file IS Ruby, so `given("x")` is ALREADY a real
+      # method call by the time any of this code runs, and Ruby's own
+      # method dispatch already refuses an ARITY mismatch on an
+      # EXISTING method for free. What Ruby's own dispatch does NOT do
+      # is consult the self-hosted grammar table AT ALL — a mistyped
+      # word (`giv3n("x")`) or a word used in the wrong context
+      # (`identified_by` inside a `command` block) just raises Ruby's
+      # own generic `NoMethodError`, naming nothing about what the
+      # language actually admits. This module closes that gap.
+      #
+      # `method_missing`/`respond_to_missing?` ONLY — a word this
+      # builder class already answers with an ordinary `def` (or a
+      # shared mixin method like `AttributeCollector#attribute`) never
+      # reaches this module at all; Ruby's own method lookup finds it
+      # first, and item #13's later slices haven't removed every one of
+      # those yet. This WAS "zero behavior change for every currently-
+      # valid line in the entire corpus" in its own first slice — since
+      # item #13's full metaprogrammed dispatch (slice 1, whole-project
+      # table-unification survey) started REMOVING the hand-written
+      # methods this module's own admissibility check used to defer to,
+      # some words now execute for real here too, via `GenericDispatch`
+      # — see that module's own header for exactly which ones, and the
+      # full account of what was verified before each was migrated. A
+      # mistyped or wrongly-contexted word still gets the same real,
+      # helpful, table-driven refusal Rust's own `word_gate` already
+      # gives, instead of Ruby's own generic `NoMethodError` — that half
+      # is genuinely unchanged.
+      #
+      # `self.class::GRAMMAR_CONTEXT` — each including class names which
+      # row of the self-hosted `Context` closed set it corresponds to
+      # (`AggregateBuilder::GRAMMAR_CONTEXT = "Aggregate"`, etc.) — the
+      # SAME string `word_gate`'s own `context` parameter already is on
+      # the Rust side, read off the identical table.
+      #
+      # BOOTSTRAPPING GATED, the same reason `RuleReference#lookup`
+      # already is (`rule_reference.rb`'s own comment has the full
+      # story) — the meta-domain's own bootstrap calls dozens of
+      # keywords on itself before its own grammar table exists to
+      # check them against. For most words, this module steps aside
+      # entirely during bootstrap (`super`, Ruby's own ordinary
+      # `NoMethodError`) — the exact behavior every builder already had
+      # before this module existed, and (unlike `RuleReference`) there
+      # is deliberately no fallback covering the whole ~200-row table —
+      # that would defeat the entire point.
+      #
+      # ONE NARROW EXCEPTION, added in item #13's full metaprogrammed
+      # dispatch (slice 3, whole-project table-unification survey):
+      # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`, a SMALL, EXPLICIT
+      # table naming the same (context, word) -> method pairs the real
+      # `calls:` column would say once it exists — used ONLY for words
+      # BOTH migrated to the `calls:` shape AND bootstrap-reachable
+      # (`attribute`, today). This is the one place in this whole arc a
+      # bootstrap fallback was worth building despite `RuleReference`'s
+      # own precedent against it: it duplicates NO logic, only a METHOD
+      # NAME — `attribute_impl`'s own real, hand-written body is called
+      # either way, bootstrap or not, so there is nothing here that can
+      # drift the way a full behavioral duplicate could.
+      #
+      # TWO FURTHER PIECES, both slice 5:
+      #   - `word_gate_dispatch` is the same admission+dispatch logic
+      #     `method_missing` below runs, factored out so a class with
+      #     its OWN class-level `method_missing` (`HecksagonBuilder`'s/
+      #     `WorldBuilder`'s genuinely open-ended verb vocabulary) can
+      #     call it directly and fall back to its own open-verb handling
+      #     only when this returns `NOT_ADMITTED` — a class-level `def`
+      #     always wins over an included module's in Ruby's own method
+      #     resolution, so their OWN `method_missing` is the only one
+      #     that ever runs for them, and this is what lets a real,
+      #     closed-set word (`port`/`realm`/`latest`) still reach
+      #     `GenericDispatch` despite that.
+      #   - the "Type"-position fallback inside `word_gate_dispatch`
+      #     itself, for `one_of`/`list_of` — called inside an
+      #     attribute's own type argument, with `self` as whatever
+      #     builder is currently `instance_eval`ing, never a dedicated
+      #     "Type" builder `self.class::GRAMMAR_CONTEXT` could ever
+      #     name. See that method's own comment.
+      module WordGate
+        # A caller with its OWN class-level `method_missing`
+        # (`HecksagonBuilder`/`WorldBuilder` — see `word_gate_dispatch`'s
+        # own header) checks for this to tell "not a word the grammar
+        # admits at all" apart from every other outcome below (a real
+        # dispatch, or a raised refusal) — never raised itself, so a
+        # caller can fall through to its own open-ended handling instead.
+        NOT_ADMITTED = Object.new.freeze
+
+        # PRIVATE, matching Ruby's own convention for both (`Object`
+        # defines them private too) — and load-bearing here, not just
+        # style: `spec/syntax_conformance_spec.rb`'s "declares every
+        # word X answers" check walks `public_instance_methods`, and a
+        # public `method_missing`/`respond_to_missing?` would show up
+        # there as two more "answered words" no row of the grammar ever
+        # declares, on every builder this module touches.
+
+        private
+
+        def method_missing(word, *args, **kwargs, &block)
+          if MetaValidator.bootstrapping?
+            fallback = GenericDispatch::BOOTSTRAP_CALLS_FALLBACK
+            # Own context first, "Type" second — the same order the
+            # ordinary (non-bootstrapping) `word_gate_dispatch` path
+            # below checks them in, for the same reason: `list_of`/
+            # `one_of` used in an attribute's own type position never
+            # arrive with `self.class::GRAMMAR_CONTEXT == "Type"`.
+            target = fallback[[self.class::GRAMMAR_CONTEXT, word.to_s]] || fallback[["Type", word.to_s]]
+            return send(target, *args, **kwargs, &block) if target
+
+            return super
+          end
+
+          result = word_gate_dispatch(word, args, kwargs, block)
+          return super if result.equal?(NOT_ADMITTED)
+
+          result
+        end
+
+        # THE CORE ADMISSION+DISPATCH LOGIC, factored out of
+        # `method_missing` — item #13's full metaprogrammed dispatch
+        # (slice 5, whole-project table-unification survey) — so a
+        # class with its OWN class-level `method_missing`
+        # (`HecksagonBuilder`'s/`WorldBuilder`'s genuinely open-ended
+        # verb vocabulary, `persisted_by "Heki"`/`posted_by "Carrier"`,
+        # can never BE a closed table) can still route a word THE
+        # GRAMMAR ADMITS through here first, falling back to its own
+        # open-verb handling only for what this doesn't recognize at
+        # all — unblocking `Hecksagon#port`/`World#realm`/`World#latest`,
+        # each a real, closed-set word that happened to sit on a class
+        # whose own `method_missing` a class-level `def` always wins
+        # over Ruby's own module-inclusion order.
+        #
+        # NEVER RAISES "not admitted" — returns `NOT_ADMITTED` instead,
+        # so the caller (this module's own `method_missing`, or one of
+        # the two above) decides what that means for it. DOES still
+        # raise the richer, table-driven refusals below once a word is
+        # admitted-but-unimplemented, or admitted-somewhere-else-only —
+        # those are real, useful refusals regardless of which
+        # `method_missing` is asking.
+        def word_gate_dispatch(word, args, kwargs, block)
+          context = self.class::GRAMMAR_CONTEXT
+          rows = MetaValidator::SyntaxBoot.call
+          keywords = rows[:keywords]
+          admitted = keywords.select { |row| row[:context] == context && (row[:word] == word.to_s || row[:was] == word.to_s) }
+
+          # THE TYPE-POSITION FALLBACK — item #13's full metaprogrammed
+          # dispatch (slice 5). `one_of`/`list_of`, called inside an
+          # attribute's own type argument (`attribute :x,
+          # one_of("a","b")`), run with `self` as whatever builder is
+          # CURRENTLY instance_eval'ing — there is no dedicated "Type"
+          # builder of its own; every attribute()-taking builder answers
+          # these identically, through the shared `AttributeCollector`
+          # mixin. `self.class::GRAMMAR_CONTEXT` can never actually BE
+          # "Type", so a word admitted only there would otherwise look
+          # inadmissible everywhere. Checked only once THIS context has
+          # already come up empty, so a context with its own same-named
+          # row (`ValueObject`'s own `one_of`, the block-wrapper form)
+          # keeps using that instead, unaffected.
+          if admitted.empty?
+            type_admitted = keywords.select { |row| row[:context] == "Type" && row[:word] == word.to_s }
+            unless type_admitted.empty?
+              admitted = type_admitted
+              context = "Type"
+            end
+          end
+
+          return NOT_ADMITTED if admitted.empty? && !admitted_anywhere?(keywords, word)
+
+          if admitted.empty?
+            legal = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }.uniq.sort
+            raise Malformed,
+                  "'#{word}' is not a word #{context} admits — legal words here: #{legal.join(', ')}"
+          end
+
+          # ITEM #13's FULL METAPROGRAMMED DISPATCH — the word IS
+          # admitted here, and this builder has no hand-written method
+          # left for it; before falling through to the "not yet
+          # implemented" refusal every word without one still gets,
+          # offer it to GenericDispatch — the SAFE, verified subset of
+          # words whose whole behavior is now executed off this same
+          # table, not just checked against it.
+          dispatched = GenericDispatch.try(self, context, word.to_s, args, kwargs, block, rows)
+          return dispatched unless dispatched.equal?(GenericDispatch::NOT_HANDLED)
+
+          raise Malformed,
+                "'#{word}' is admitted by #{context}'s own grammar, but #{self.class} has no " \
+                "builder method for it yet — not yet implemented"
+        end
+
+        def respond_to_missing?(word, include_private = false)
+          return super if MetaValidator.bootstrapping?
+
+          context = self.class::GRAMMAR_CONTEXT
+          keywords = MetaValidator::SyntaxBoot.call[:keywords]
+          keywords.any? { |row| row[:context] == context && (row[:word] == word.to_s || row[:was] == word.to_s) } ||
+            keywords.any? { |row| row[:context] == "Type" && row[:word] == word.to_s } ||
+            super
+        end
+
+        # A word admitted SOMEWHERE, just not in THIS context, still
+        # falls through to Ruby's own `NoMethodError` rather than this
+        # module's own richer refusal — `method_missing` fires for
+        # every typo in the whole codebase (this class's own genuinely
+        # private helper methods included), not just DSL keyword calls;
+        # only raise the RICH, table-driven message when the word is at
+        # least SOMETHING the grammar knows about, anywhere, so an
+        # unrelated Ruby-level typo inside a builder's own private code
+        # keeps its own ordinary, unconfusing `NoMethodError`.
+        def admitted_anywhere?(rows, word)
+          rows.any? { |row| row[:word] == word.to_s || row[:was] == word.to_s }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+require_relative "word_gate"
+module Hecks
+  module Bluebook
+    module DSL
+      class SettingsCollector
+        def initialize = @values = {}
+
+        def method_missing(key, *args, &_block)
+          @values[key.to_sym] = args.size == 1 ? args.first : args
+        end
+
+        def respond_to_missing?(_name, _include_private = false) = true
+
+        def to_h = @values
+      end
+
+      class WorldBuilder
+        GRAMMAR_CONTEXT = "World"
+
+        include WordGate
+
+        def initialize(domain)
+          @domain   = domain
+          @settings = {}
+        end
+
+        # RENAMED FROM `realm`/`latest` — item #13's full metaprogrammed
+        # dispatch (slice 5). Neither bootstrap-reachable (checked
+        # directly). Reached through `WordGate#method_missing`'s new
+        # `word_gate_dispatch`, called explicitly below since
+        # `WorldBuilder`'s own class-level `method_missing` (the
+        # open-verb catch-all beneath this) always wins over the
+        # module's — see `word_gate.rb`'s own header for the full
+        # mechanism.
+        def realm_impl(value)
+          @realm = required(value, "realm")
+        end
+
+        def latest_impl(value)
+          @latest = required(value, "latest version")
+        end
+
+        def method_missing(verb, *args, **kwargs, &block)
+          result = word_gate_dispatch(verb, args, kwargs, block)
+          return result unless result.equal?(WordGate::NOT_ADMITTED)
+
+          collector = SettingsCollector.new
+          collector.instance_eval(&block) if block
+          value = { adapter: args.first.to_s }.merge(kwargs).merge(collector.to_h)
+          @settings[verb.to_s] = value
+          @settings["#{verb}:#{args.first.to_s.downcase}"] = value
+        end
+
+        def respond_to_missing?(_name, _include_private = false) = true
+
+        def build
+          MetaValidator.call_world(
+            World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings)
+          )
+        end
+
+        def self.build(domain, &block)
+          builder = new(domain)
+          builder.instance_eval(&block) if block
+          builder.build
+        end
+
+        private
+
+        def required(value, label)
+          # moved to the language: Realm / Latest invariants, in world.bluebook
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl.rb

@@ -0,0 +1,45 @@
+module Hecks
+  module Bluebook
+    # The authoring surface — one builder per declaration kind, collecting
+    # what a .bluebook file says into the IR. Builders call the
+    # meta-validator at build time, not at load time, so their require
+    # order here is the readable one.
+    module DSL
+    end
+  end
+end
+
+# The query/read-model builders reach QuerySpecification at class-body
+# level and cannot say so themselves (contents frozen) — the namespace
+# file says it for them. The builders also build IR, at build time.
+require_relative "../construct"
+require_relative "../query_specification"
+# The model the builders construct — `bluebook.rb` requires the whole
+# set; this names the one file that declares the chapter class itself,
+# which every builder returns into.
+require_relative "chapter"
+
+require_relative "dsl/malformed"
+require_relative "dsl/const_shim"
+require_relative "dsl/attribute_collector"
+require_relative "dsl/identity_declaration"
+require_relative "dsl/rule_reference"
+require_relative "dsl/word_gate"
+require_relative "dsl/value_object_builder"
+require_relative "dsl/command_builder"
+require_relative "dsl/lifecycle_builder"
+require_relative "dsl/query_builder"
+require_relative "dsl/read_model_builder"
+require_relative "dsl/entity_builder"
+require_relative "dsl/policy_builder"
+require_relative "dsl/process_manager_builder"
+require_relative "dsl/port_operation_builder"
+require_relative "dsl/domain_port_builder"
+require_relative "dsl/aggregate_builder"
+require_relative "dsl/bluebook_builder"
+require_relative "dsl/binding_proxy"
+require_relative "dsl/hecksagon_builder"
+require_relative "dsl/port_builder"
+require_relative "dsl/adapter_builder"
+require_relative "dsl/world_builder"
+require_relative "dsl/translation_builder"

data/lib/hecks/bluebook/entity.rb

@@ -0,0 +1,103 @@
+require_relative "behaviour/entity"
+
+module Hecks
+  module Bluebook
+    # An entity, as a RUBY CLASS — a piece of an aggregate that has an identity
+    # of its own.
+    #
+    # Crossing over closes the OWNER CHAIN. An entity declares commands, and
+    # until now those commands had no owner that could state an identity: an
+    # entity was an IR object, not a construct, so `Construct#hecks_fqn` refused
+    # rather than answering "Deposit" and looking right. Four of banking's
+    # commands were in that state. They can say what they are now —
+    # `Banking::Account.Ledger.Deposit` — which is the id the judge already mints
+    # for them.
+    #
+    # NOT const_set, for the same reason a command is not: a name inside one
+    # aggregate can denote more than one kind of thing, so the constant tree
+    # cannot index it.
+    #
+    # It must stay STRUCTURALLY INTERCHANGEABLE with an aggregate — the runtime
+    # builds `Instance.new(aggregate: entity)` and `CommandRules` takes either as
+    # `declaring` — so it answers `hecks_name`, `attributes`, `attribute`,
+    # `identified_by` and `lifecycle` exactly as an aggregate does. And it must
+    # keep NOT answering `value_object`: `Value.for_attribute` sniffs for that
+    # method to tell a piece from a head.
+    class Entity
+      extend Construct
+      extend Hecks::IR
+      extend Behaviour::Entity
+
+      emits_ir(
+        name:          :hecks_name,
+        description:   :description,
+        identified_by: :identity_paths,
+        attributes:    many(:attributes),
+        commands:      many(:commands),
+        queries:       many(:queries),
+        # S17, ADR 0026 — "That is what `entity` is for, and `entity` is
+        # declared by the language and used zero times in it" (the ADR's
+        # own words). Dispatch nests inside Handler, so an entity's own
+        # NESTED entities are part of its wire shape now, the same way
+        # an aggregate's always were — the field the ADR names as
+        # declared-but-unused until this slice.
+        entities:      many(:entities),
+        # ADR 0028 — a piece's own `given`, the SAME shape
+        # `Aggregate#preconditions` already carries (its own `emits_ir`
+        # row, identical). A precondition shared across this piece's own
+        # commands, declared once — a command references it back by
+        # name; the resolved text still lands on EACH referencing
+        # command's own `givens` either way, so this field is read-only
+        # documentation of what the piece itself declared, the same
+        # relationship `Aggregate.preconditions` already has to its own
+        # commands.
+        preconditions: -> { preconditions.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        # A piece's OWN shape rule, checked against EVERY instance of
+        # this piece the aggregate holds (Admissibility#enforce_
+        # invariants' own recursive walk) — the SAME relationship
+        # `ValueObject#invariants` already has to its own instances,
+        # one level up the construct tree. Not a separate enforcement
+        # boundary; still checked at the SAME two points (after every
+        # mutation, before save) the aggregate's own invariants always
+        # were — see that method's own comment for why this does not
+        # contradict "there is no separate entity invariant."
+        invariants:    -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        lifecycle:     one(:lifecycle)
+      )
+
+      class << self
+        attr_reader :description, :identified_by, :identity_paths, :identity_heads,
+                    :attributes, :commands, :queries, :entities, :preconditions, :invariants, :lifecycle
+
+        def declare(name:, description: nil, identified_by: nil, attributes: [],
+                    commands: [], queries: [], entities: [], preconditions: [], invariants: [], lifecycle: nil)
+          piece = Class.new(self)
+          piece.hecks_name = name.to_s
+          piece.absorb(description: description, identified_by: identified_by,
+                       attributes: attributes, commands: commands,
+                       queries: queries, entities: entities, preconditions: preconditions,
+                       invariants: invariants, lifecycle: lifecycle)
+          piece.stamp_children
+          piece
+        end
+
+        # Assigns what the language declares, then hands off to the
+        # behaviour's own `settle` — derived identity and the name
+        # indexes, neither of which the declaration states.
+        def absorb(description:, identified_by:, attributes:, commands:, queries:, entities:, preconditions:, invariants:, lifecycle:)
+          @description    = description
+          @identified_by  = identified_by
+          @attributes     = attributes
+          @commands       = commands
+          @queries        = queries
+          @entities       = entities
+          @preconditions  = preconditions
+          @invariants     = invariants
+          @lifecycle      = lifecycle
+
+          settle
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/expression/canonical_form.rb

@@ -0,0 +1,55 @@
+require "json"
+require_relative "../../vocabulary"
+
+module Hecks
+  module Bluebook
+    module Expression
+      module CanonicalForm
+        Rule = Struct.new(:strategy, :source_token, :replacement, :boundary, :position, keyword_init: true)
+
+        STRATEGIES = Hecks::Vocabulary.fetch("NormalisationStrategy")
+
+        # READ, NOT RESTATED — the admitted normalisation rules, projected
+        # from the grammar chapter by bin/expression_projection exactly as
+        # the evaluator's operator table is. See Evaluator::PROJECTION for
+        # why a projection rather than a boot.
+        RULES = JSON.parse(
+          File.read(File.join(__dir__, "projection.json")), symbolize_names: true
+        ).fetch(:normalisations).map { |row| Rule.new(**row) }.freeze
+
+        module_function
+
+        def table
+          RULES.sort_by(&:position).map do |rule|
+            {
+              strategy:     rule.strategy,
+              source_token: rule.source_token,
+              replacement:  rule.replacement,
+              boundary:     rule.boundary,
+              position:     rule.position.to_s
+            }
+          end
+        end
+
+        def apply(source)
+          RULES.sort_by(&:position).reduce(source.to_s) { |text, rule| step(text, rule) }.strip
+        end
+
+        def step(text, rule)
+          case rule.strategy
+          when "collapse_whitespace" then text.gsub(/\s+/, " ")
+          when "replace"             then replace(text, rule)
+          else
+            raise ArgumentError, "#{rule.strategy.inspect} is not a linked normalisation strategy"
+          end
+        end
+
+        def replace(text, rule)
+          return text.gsub(rule.source_token, rule.replacement) if rule.boundary == "none"
+
+          text.gsub(/#{Regexp.escape(rule.source_token)}(?![[:alnum:]_])/, rule.replacement)
+        end
+      end
+    end
+  end
+end