hecks 3.5.0 → 3.6.0

data/lib/hecks/ports/authentication.rb

@@ -47,17 +47,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can authenticate a sign-in"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can authenticate a sign-in" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/authorization.rb

@@ -57,17 +57,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can answer a role check"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can answer a role check" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/clock.rb

@@ -26,17 +26,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can say what time it is"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can say what time it is" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/extraction.rb

@@ -33,19 +33,20 @@ module Hecks
         end
 
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can recover a " \
-                "predicate's source"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime " \
-                "will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can recover a predicate's source" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/identity_assignment.rb

@@ -28,17 +28,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can assign an identity"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can assign an identity" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/identity_generation.rb

@@ -23,17 +23,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can mint an identity"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can mint an identity" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/identity_resolution.rb

@@ -31,17 +31,20 @@ module Hecks
       #   or the one that does has no Ruby implementation under `Hecks::Adapters`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can resolve an identity"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can resolve an identity" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/key_vault.rb

@@ -32,17 +32,20 @@ module Hecks
       # Refuses an ambiguous wiring rather than choosing an adapter arbitrarily.
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can issue or destroy a key"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can issue or destroy a key" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/persistence/append_only.rb

@@ -40,10 +40,10 @@ module Hecks
           @adapter = adapter
           required = %i[append project entries]
           missing = required.reject { |method| adapter.respond_to?(method) }
-          unless missing.empty?
-            raise Runtime::WiringError,
-                  "#{adapter.class} does not implement append-only persistence: #{missing.join(', ')}"
-          end
+          return if missing.empty?
+
+          raise Runtime::WiringError,
+                "#{adapter.class} does not implement append-only persistence: #{missing.join(", ")}"
         end
 
         # Reads one record's current projected state from the adapter.
@@ -228,7 +228,7 @@ module Hecks
         # @return [Boolean] true when a record was found and deleted, false when there was
         #   none and nothing was journaled
         # @raise [Runtime::WiringError] when the adapter's `append` or `project` refuses
-        def delete(id)
+        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, answering whether a record existed
           return false unless find(id)
 
           entry = Entry.new(operation: "delete", id: id.to_s, state: nil)

data/lib/hecks/ports/persistence/binding_policy.rb

@@ -1,4 +1,4 @@
-require_relative "../../bluebook/hexagon"
+require_relative "../../bluebook/hecksagon"
 require_relative "../../runtime/registry"
 
 module Hecks
@@ -20,21 +20,45 @@ module Hecks
         # @raise [Runtime::WiringError] if the hecksagon has no `persisted_by` bind for the
         #   aggregate, more or fewer than one bind without a role, or any bind with a role
         def resolve(registry, domain, aggregate)
-          hexagon  = registry.hecksagon(domain)
-          declared = registry.default_adapter_for(domain)
-          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hexagon
+          hecksagon = registry.hecksagon(domain)
+          declared  = registry.default_adapter_for(domain)
+          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hecksagon
 
-          bindings = hexagon.binds_for(aggregate.hecks_name, VERB)
-          bindings = [default_binding(aggregate, declared)] if bindings.empty? && declared
+          bindings = declared_bindings(hecksagon, aggregate, declared)
           raise missing_binding(domain, aggregate) if bindings.empty?
 
+          authoritative_among(bindings, domain, aggregate)
+        end
+
+        # Picks the single roleless bind, refusing any other count and any bind with a role.
+        #
+        # @param bindings [Array<Bluebook::Bind>] the aggregate's binds; not empty
+        # @param domain [String, Symbol] name of the domain, used in refusal messages
+        # @param aggregate [Bluebook::Aggregate] the aggregate the binds belong to
+        # @return [Bluebook::Bind] the authoritative bind
+        # @raise [Runtime::WiringError] if the roleless count is not one, or a role is present
+        def authoritative_among(bindings, domain, aggregate)
           authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
           raise ambiguous_binding(domain, aggregate, authoritative) unless authoritative.size == 1
-          raise unsupported_roles(domain, aggregate, bindings - authoritative) unless (bindings - authoritative).empty?
+
+          roled = bindings - authoritative
+          raise unsupported_roles(domain, aggregate, roled) unless roled.empty?
 
           authoritative.first
         end
 
+        # Lists the hecksagon's `persisted_by` binds for an aggregate, or the world's default
+        # adapter bind when the hecksagon declares none.
+        #
+        # @param hecksagon [Bluebook::Hexagon] the domain's hecksagon
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose binds are wanted
+        # @param declared [String, nil] the world's default adapter, if any
+        # @return [Array<Bluebook::Bind>] the binds; empty when none and no default exists
+        def declared_bindings(hecksagon, aggregate, declared)
+          bindings = hecksagon.binds_for(aggregate.hecks_name, VERB)
+          bindings.empty? && declared ? [default_binding(aggregate, declared)] : bindings
+        end
+
         # Builds the bind an aggregate gets when its domain declares no hecksagon.
         #
         # @param aggregate [Bluebook::Aggregate] the aggregate to bind
@@ -81,8 +105,8 @@ module Hecks
         # @return [Runtime::WiringError] an error whose message lists each role
         def unsupported_roles(domain, aggregate, bindings)
           Runtime::WiringError.new(
-            "#{domain}::#{aggregate.hecks_name} uses persistence role#{'s' unless bindings.size == 1} " \
-            "#{bindings.map(&:role).map(&:inspect).join(', ')}. Only persisted_by is supported."
+            "#{domain}::#{aggregate.hecks_name} uses persistence role#{"s" unless bindings.size == 1} " \
+            "#{bindings.map { |binding| binding.role.inspect }.join(", ")}. Only persisted_by is supported."
           )
         end
       end

data/lib/hecks/ports/persistence/codec_boundary.rb

@@ -91,17 +91,28 @@ module Hecks
         # @param klass [Class] the adapter's class
         # @return [Module] an anonymous module including `Guarded`, to `extend` onto instances
         def wrapper_for(klass)
-          WRAPPERS_LOCK.synchronize do
-            WRAPPERS[klass] ||= Module.new do
-              include Guarded
-
-              (klass.public_instance_methods - Object.public_instance_methods).each do |name|
-                define_method(name) do |*args, **kwargs, &block|
-                  result = CodecBoundary.within { super(*args, **kwargs, &CodecBoundary.outside_block(block)) }
-                  name == :entries ? CodecBoundary.check_entries!(self, result) : result
-                end
-              end
-            end
+          WRAPPERS_LOCK.synchronize { WRAPPERS[klass] ||= build_wrapper(klass) }
+        end
+
+        # Builds the module whose methods forward to the adapter class's own, inside the boundary.
+        #
+        # @param klass [Class] the adapter's class
+        # @return [Module] an anonymous module including `Guarded`
+        def build_wrapper(klass)
+          wrapper = Module.new { include Guarded }
+          (klass.public_instance_methods - Object.public_instance_methods).each { |name| guard_method(wrapper, name) }
+          wrapper
+        end
+
+        # Defines one guarded method on `wrapper`; `entries` answers are also checked for decoding.
+        #
+        # @param wrapper [Module] the module under construction
+        # @param name [Symbol] the adapter method to guard
+        # @return [Symbol] the defined method name
+        def guard_method(wrapper, name)
+          wrapper.define_method(name) do |*args, **kwargs, &block|
+            result = CodecBoundary.within { super(*args, **kwargs, &CodecBoundary.outside_block(block)) }
+            name == :entries ? CodecBoundary.check_entries!(self, result) : result
           end
         end
 

data/lib/hecks/ports/persistence/constants.rb

@@ -0,0 +1,10 @@
+module Hecks
+  module Ports
+    # The persistence port's identifying names, loaded before the files that read them.
+    module Persistence
+      NAME = "persistence".freeze
+      VERB = "persisted_by".freeze
+      DEFAULT_ADAPTER = "Memory".freeze
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -128,19 +128,13 @@ module Hecks
       def fallback_source_files(bluebook, directory, domain_files, registry)
         vendored_name = registry && vendored_bluebook_name_for(registry, bluebook.name)
         framework_path = Framework.members[bluebook.name]
+        return [framework_path] if framework_path
+        return vendored_source_for(directory, vendored_name) if vendored_name
+
         attached = Chapters.index.fetch(bluebook.name, [])
+        return attached if attached.any?
 
-        if attached.any? && !framework_path && !vendored_name
-          attached
-        elsif domain_files.size == 1 && !framework_path && !vendored_name
-          domain_files
-        elsif framework_path
-          [framework_path]
-        elsif vendored_name
-          vendored_source_for(directory, vendored_name)
-        else
-          []
-        end
+        domain_files.size == 1 ? domain_files : []
       end
 
       # Recovers the vendored package name behind a bluebook, if some hecksagon vendored it.
@@ -196,11 +190,7 @@ module Hecks
         adapter_name = adapter_for(registry, bluebook.name, first)
         return unless lineage_capable?(registry, adapter_name)
 
-        unless current_text
-          raise WiringError,
-                "cannot boot #{bluebook.name}: bound to a lineage-capable adapter, but no source file for " \
-                "it could be found (checked #{directory.inspect} and the framework registry)"
-        end
+        refuse_missing_source!(bluebook, directory) unless current_text
 
         settings = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter_name)
         registry.adapter_class(adapter_name).era_check!(
@@ -209,6 +199,18 @@ module Hecks
         )
       end
 
+      # Refuses the boot of a lineage-bound bluebook whose source file was not found.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook being checked
+      # @param directory [String, nil] the domain's bluebook directory, named in the message
+      # @return [void]
+      # @raise [Runtime::WiringError] always
+      def refuse_missing_source!(bluebook, directory)
+        raise WiringError,
+              "cannot boot #{bluebook.name}: bound to a lineage-capable adapter, but no source file for " \
+              "it could be found (checked #{directory.inspect} and the framework registry)"
+      end
+
       # Refuses the boot when one bluebook's compute rule is bound away from Postgres.
       #
       # A compute rule's SQL is its only implementation, so it cannot

data/lib/hecks/ports/persistence/plugins/era/era_guard/shape_diff.rb

@@ -4,6 +4,9 @@ module Hecks
       # Structural signature and diff of aggregate shapes, computed from the IR alone
       # (no file I/O), so the Postgres mint path can call it too.
       module ShapeDiff
+        # The held and current aggregates being compared, with the lineage that may explain drift.
+        Sides = Struct.new(:held_aggregate, :aggregate, :lineage)
+
         # Structural signature of an aggregate: sorted `[name, signature]` pairs per attribute.
         def shape(aggregate)
           aggregate.attributes.map do |attribute|
@@ -42,16 +45,14 @@ module Hecks
 
         # True when a new attribute could be genuinely absent from an existing record (ADR 0025).
         def possibly_absent?(aggregate, attribute)
-          return false if attribute.optional?
-          return false unless attribute.default.nil?
-          return false if attribute.list?
-
-          value_object = aggregate.value_object(attribute.type)
-          return false if value_object&.attributes&.all? { |field| !field.default.nil? }
+          return false if attribute.optional? || !attribute.default.nil? || attribute.list?
 
-          true
+          !fully_defaulted?(aggregate.value_object(attribute.type))
         end
 
+        # True when a value object exists and every member of it carries a default.
+        def fully_defaulted?(value_object) = value_object&.attributes&.all? { |field| !field.default.nil? }
+
         # Held attribute paths that vanished or changed type with no rule explaining them,
         # recursing into value objects as dotted paths ("price.currency"). Additions never count.
         def uncovered_attributes(aggregate, held_aggregate, lineage)
@@ -59,7 +60,8 @@ module Hecks
             current_attribute = aggregate.attribute(held_attribute.name)
             next [held_attribute.name.to_s] unless current_attribute
 
-            diff_type(held_attribute.name.to_s, held_attribute.type, current_attribute.type, held_aggregate, aggregate, lineage)
+            sides = Sides.new(held_aggregate, aggregate, lineage)
+            diff_type(held_attribute.name.to_s, held_attribute.type, current_attribute.type, sides)
           end
 
           return paths unless lineage
@@ -70,24 +72,31 @@ module Hecks
         # Compares one path's held and current types, recursing into shared members.
         # A `list_of` entity is diffed only for member drift; no per-element translation exists, so
         # only a top-level `drop` of the whole list satisfies it.
-        def diff_type(path, held_type, current_type, held_aggregate, aggregate, lineage, seen = [])
-          if held_type != current_type
-            # A declared retype accepts the pair but members are still compared, so drift
-            # hidden under the rename is caught.
-            return [path] unless lineage&.retype?(held_type, current_type)
-          end
+        def diff_type(path, held_type, current_type, sides, seen = [])
+          return [path] if retype_drift?(held_type, current_type, sides.lineage)
           return [] if seen.include?(current_type)
 
-          held_container = nested_type(held_aggregate, held_type)
-          current_container = nested_type(aggregate, current_type)
+          held_container = nested_type(sides.held_aggregate, held_type)
+          current_container = nested_type(sides.aggregate, current_type)
           return [] unless held_container && current_container
 
+          diff_members(path, [held_container, current_container], sides, seen + [current_type])
+        end
+
+        # A declared retype accepts the pair but members are still compared, so drift
+        # hidden under the rename is caught.
+        def retype_drift?(held_type, current_type, lineage)
+          held_type != current_type && !lineage&.retype?(held_type, current_type)
+        end
+
+        # Diffs each member of the held container against the same-named current member.
+        def diff_members(path, containers, sides, seen)
+          held_container, current_container = containers
           held_container.attributes.flat_map do |held_member|
             current_member = current_container.attribute(held_member.name)
             next ["#{path}.#{held_member.name}"] unless current_member
 
-            diff_type("#{path}.#{held_member.name}", held_member.type, current_member.type, held_aggregate, aggregate, lineage,
-                      seen + [current_type])
+            diff_type("#{path}.#{held_member.name}", held_member.type, current_member.type, sides, seen)
           end
         end
       end