hecks 3.5.0 → 3.6.0

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_one.rb

@@ -17,22 +17,29 @@ module Hecks
         # @param after [Hash{String => Hash}] translated state per record id, as parsed JSON
         # @return [void]
         def layer_one!(violations, aggregate, after)
-          after.each do |id, state|
-            symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
-            instance = Runtime::Instance.new(aggregate: aggregate, id: id, state: symbolized)
-            lifecycle = aggregate.lifecycle
-            next unless lifecycle
+          after.each { |id, state| check_record!(violations, aggregate, id, state) }
+        end
+
+        private
+
+        def check_record!(violations, aggregate, id, state)
+          symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
+          instance = Runtime::Instance.new(aggregate: aggregate, id: id, state: symbolized)
+          lifecycle = aggregate.lifecycle
+          return unless lifecycle
+
+          check_lifecycle_state!(violations, aggregate, id, lifecycle, instance[lifecycle.field])
+        rescue Runtime::InvariantViolation, Runtime::TypeMismatch => e
+          violations << "#{aggregate.name}##{id}: #{e.message}"
+        end
+
+        def check_lifecycle_state!(violations, aggregate, id, lifecycle, held)
+          # `Lifecycle#states` omits states declared only as a `from:`; `full_states` has them.
+          allowed = Bluebook::ModelCheck.full_states(lifecycle)
+          return if held.nil? || allowed.include?(held.to_s)
 
-            held = instance[lifecycle.field]
-            # `Lifecycle#states` omits states declared only as a `from:`; `full_states` has them.
-            allowed = Bluebook::ModelCheck.full_states(lifecycle)
-            unless held.nil? || allowed.include?(held.to_s)
-              violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \
-                            "a state this era's lifecycle never reaches"
-            end
-          rescue Runtime::InvariantViolation, Runtime::TypeMismatch => e
-            violations << "#{aggregate.name}##{id}: #{e.message}"
-          end
+          violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \
+                        "a state this era's lifecycle never reaches"
         end
       end
     end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_two.rb

@@ -41,18 +41,8 @@ module Hecks
         # @return [void]
         def check_id_conservation!(violations, aggregate, before, after, rekeyed:)
           # A rekey changes the id set, so compare counts: a collision or a NULL id lowers it.
-          if rekeyed
-            unless before.keys.size == after.keys.size
-              violations << "#{aggregate.name}: the record count changed across a rekeying edge " \
-                            "(#{before.keys.size} before, #{after.keys.size} after) — a rekey must not " \
-                            "collide two distinct ids onto one, or drop one"
-            end
-          elsif before.keys.sort != after.keys.sort
-            gained = after.keys - before.keys
-            lost = before.keys - after.keys
-            violations << "#{aggregate.name}: the id set changed across the edge " \
-                          "(lost #{lost.sort.inspect}, gained #{gained.sort.inspect})"
-          end
+          message = rekeyed ? rekey_count_violation(aggregate, before, after) : id_set_violation(aggregate, before, after)
+          violations << message if message
         end
 
         # Records a violation for each record whose translated state diverges from the reference.
@@ -66,19 +56,16 @@ module Hecks
         # @return [void]
         def check_value_preservation!(violations, aggregate, declared, before, after)
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
-          compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
+          compute_paths = compute_paths_of(declared)
 
           before.each do |id, state|
             next unless after.key?(id)
 
-            entry = Ports::Persistence::Entry.new(operation: "save", id: id, state: state.transform_keys(&:to_sym))
-            expected = strip_compute_paths(normalize(rules.translate(entry).state), compute_paths)
-            actual = strip_compute_paths(normalize(after[id]), compute_paths)
-            next if expected == actual
+            diverged = divergence(rules, id, state, after[id], compute_paths)
+            next if diverged.empty?
 
-            diverged = (expected.keys | actual.keys).reject { |key| expected[key] == actual[key] }
             violations << "#{aggregate.name}##{id}: the translated state diverges from the reference " \
-                          "transform at #{diverged.sort.join(', ')}"
+                          "transform at #{diverged.sort.join(", ")}"
           end
         end
 
@@ -109,6 +96,39 @@ module Hecks
           end
           state
         end
+
+        private
+
+        # The message for a rekeying edge whose record count changed, or nil.
+        def rekey_count_violation(aggregate, before, after)
+          return if before.keys.size == after.keys.size
+
+          "#{aggregate.name}: the record count changed across a rekeying edge " \
+            "(#{before.keys.size} before, #{after.keys.size} after) — a rekey must not " \
+            "collide two distinct ids onto one, or drop one"
+        end
+
+        # The message for an edge whose id set changed, or nil.
+        def id_set_violation(aggregate, before, after)
+          return if before.keys.sort == after.keys.sort
+
+          gained = after.keys - before.keys
+          lost = before.keys - after.keys
+          "#{aggregate.name}: the id set changed across the edge " \
+            "(lost #{lost.sort.inspect}, gained #{gained.sort.inspect})"
+        end
+
+        def compute_paths_of(declared)
+          declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
+        end
+
+        # The keys at which one record's translated state differs from the reference transform.
+        def divergence(rules, id, state, translated, compute_paths)
+          entry = Ports::Persistence::Entry.new(operation: "save", id: id, state: state.transform_keys(&:to_sym))
+          expected = strip_compute_paths(normalize(rules.translate(entry).state), compute_paths)
+          actual = strip_compute_paths(normalize(translated), compute_paths)
+          (expected.keys | actual.keys).reject { |key| expected[key] == actual[key] }
+        end
       end
     end
   end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/unfed_report.rb

@@ -12,28 +12,28 @@ module Hecks
         # @param after [Hash{String => Hash}] translated state per record id
         # @return [Array<String>] names of unfed attributes, in declaration order; `[]` when
         #   every attribute is fed or `after` holds no records
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/PerceivedComplexity
         def unfed(aggregate, declared, after)
-          fed = if declared
-                  (declared.renames.values.map(&:to_s) +
-                   declared.moves.map(&:to) +
-                   declared.converts.map(&:to) +
-                   declared.computes.map(&:to)).map { |path| path.to_s.split(".").first }
-                else
-                  []
-                end
+          return [] if after.empty?
+
+          fed = fed_names(declared)
           aggregate.attributes.filter_map do |attribute|
             name = attribute.name.to_s
-            next if fed.include?(name)
-            next unless attribute.default.nil?
-            next if after.any? { |_, state| !dig_path(state, name).nil? }
-            next if after.empty?
-
-            name
+            name unless fed.include?(name) || !attribute.default.nil? || after.any? { |_, state| !dig_path(state, name).nil? }
           end
         end
 
+        # The top-level attribute names an edge's destinations feed.
+        #
+        # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules
+        # @return [Array<String>] the destinations of renames, moves, converts and computes, cut to
+        #   their top-level name; `[]` when there is no edge
+        def fed_names(declared)
+          return [] unless declared
+
+          rules = [declared.moves, declared.converts, declared.computes].flat_map { |list| list.map(&:to) }
+          (declared.renames.values.map(&:to_s) + rules).map { |path| path.to_s.split(".").first }
+        end
+
         # Reads a dotted path out of a state whose keys may be Strings or Symbols.
         #
         # @param state [Hash, nil] the state to read

data/lib/hecks/ports/persistence/plugins/era/translation/rule_compiler.rb

@@ -10,32 +10,55 @@ module Hecks
       # Compiles one edge's rename/move/convert/drop/compute/backfill rules into a nested
       # SQL expression over `state`, composed innermost-first in that phase order.
       def compile_rules(declared)
-        expression = "state"
-        declared.renames.each do |old_name, new_name|
-          expression = "hecks_tr_rename(#{expression}, #{text_literal(old_name)}, #{text_literal(new_name)})"
-        end
-        declared.moves.each do |move|
-          expression = "hecks_tr_move(#{expression}, #{path_literal(move.from)}, #{path_literal(move.to)}, " \
-                       "#{text_literal("move #{move.from} to: #{move.to}")})"
-        end
-        declared.converts.each do |convert|
-          pairs = JSON.generate(convert.values.map { |key, value| [key, value] })
-          expression = "hecks_tr_convert(#{expression}, #{path_literal(convert.from)}, #{path_literal(convert.to)}, " \
-                       "#{text_literal(pairs)}::jsonb, #{text_literal(convert.from)}, " \
-                       "#{text_literal("convert #{convert.from} to: #{convert.to}")})"
-        end
-        declared.drops.each do |name|
-          expression = "hecks_tr_drop(#{expression}, #{path_literal(name)})"
-        end
-        declared.computes.each do |compute|
-          expression = compile_compute(expression, compute)
-        end
+        expression = compile_renames("state", declared.renames)
+        expression = compile_moves(expression, declared.moves)
+        expression = compile_converts(expression, declared.converts)
+        expression = compile_drops(expression, declared.drops)
+        expression = compile_computes(expression, declared.computes)
         # Backfilled last, same order as `Lineage#translate`'s in-process pass, so the
         # boot-time mint audit (which reads only this compiled SQL) sees the same result.
-        declared.backfills.each do |backfill|
-          expression = compile_backfill(expression, backfill)
-        end
-        expression
+        compile_backfills(expression, declared.backfills)
+      end
+
+      # Folds each rule of one kind into `expression`, innermost-first.
+      def compile_renames(expression, renames)
+        renames.inject(expression) { |sql, (old_name, new_name)| compile_rename(sql, old_name, new_name) }
+      end
+
+      def compile_moves(expression, moves) = moves.inject(expression) { |sql, move| compile_move(sql, move) }
+
+      def compile_converts(expression, converts) = converts.inject(expression) { |sql, convert| compile_convert(sql, convert) }
+
+      def compile_drops(expression, drops) = drops.inject(expression) { |sql, name| compile_drop(sql, name) }
+
+      def compile_computes(expression, computes) = computes.inject(expression) { |sql, compute| compile_compute(sql, compute) }
+
+      def compile_backfills(expression, backfills)
+        backfills.inject(expression) { |sql, backfill| compile_backfill(sql, backfill) }
+      end
+
+      # Wraps `expression` in the rename of one top-level key.
+      def compile_rename(expression, old_name, new_name)
+        "hecks_tr_rename(#{expression}, #{text_literal(old_name)}, #{text_literal(new_name)})"
+      end
+
+      # Wraps `expression` in the move of one path to another.
+      def compile_move(expression, move)
+        "hecks_tr_move(#{expression}, #{path_literal(move.from)}, #{path_literal(move.to)}, " \
+          "#{text_literal("move #{move.from} to: #{move.to}")})"
+      end
+
+      # Wraps `expression` in the conversion of one path's value through a lookup table.
+      def compile_convert(expression, convert)
+        pairs = JSON.generate(convert.values.map { |key, value| [key, value] })
+        "hecks_tr_convert(#{expression}, #{path_literal(convert.from)}, #{path_literal(convert.to)}, " \
+          "#{text_literal(pairs)}::jsonb, #{text_literal(convert.from)}, " \
+          "#{text_literal("convert #{convert.from} to: #{convert.to}")})"
+      end
+
+      # Wraps `expression` in the removal of one path.
+      def compile_drop(expression, name)
+        "hecks_tr_drop(#{expression}, #{path_literal(name)})"
       end
 
       # Reports whether an edge's declared rules for an aggregate include a rekey, read
@@ -93,7 +116,7 @@ module Hecks
       # Renders a dotted path as a SQL `text[]` array literal, one element per segment.
       def path_literal(path)
         segments = path.to_s.split(".").map { |segment| text_literal(segment) }
-        "ARRAY[#{segments.join(', ')}]::text[]"
+        "ARRAY[#{segments.join(", ")}]::text[]"
       end
     end
   end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/differ.rb

@@ -1,4 +1,5 @@
 require_relative "../../storage_shape"
+require_relative "path_diff"
 
 module Hecks
   module Translation
@@ -6,6 +7,8 @@ module Hecks
       # Diffs two eras' storage shapes into the edge's declarations; rules are written only
       # for unique signature pairs, everything else is left unresolved.
       module Differ
+        include PathDiff
+
         # Diffs two bluebook IRs into the edge's declarations.
         #
         # @param held_bluebook [Bluebook::Chapter] the era being translated from
@@ -19,19 +22,24 @@ module Hecks
 
           matched = match_aggregates(held_shapes, current_shapes)
           aggregates = current_bluebook.aggregates.filter_map do |aggregate|
-            held_name = matched[:pairs][aggregate.name]
-            next unless held_name
-
-            rules = attribute_rules(held_shapes[held_name], current_shapes[aggregate.name])
-            was = held_name == aggregate.name ? nil : held_name
-            next if rules.empty? && was.nil?
-
-            ScaffoldedAggregate.new(name: aggregate.name, was: was, rules: rules)
+            scaffolded(aggregate, matched[:pairs], held_shapes, current_shapes)
           end
 
           { aggregates: aggregates, retired: matched[:retired], unclaimed: matched[:unclaimed] }
         end
 
+        # One current aggregate's scaffolded rules, or nil when it is new or unchanged.
+        def scaffolded(aggregate, pairs, held_shapes, current_shapes)
+          held_name = pairs[aggregate.name]
+          return unless held_name
+
+          rules = attribute_rules(held_shapes[held_name], current_shapes[aggregate.name])
+          was = held_name == aggregate.name ? nil : held_name
+          return if rules.empty? && was.nil?
+
+          ScaffoldedAggregate.new(name: aggregate.name, was: was, rules: rules)
+        end
+
         # Projects a bluebook's storage shape, indexing its aggregates by name.
         def projections(bluebook)
           Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
@@ -46,25 +54,28 @@ module Hecks
         # @return [Hash{Symbol => Object}] `:pairs` (current name to held name, or nil),
         #   `:retired` (Array<String>), `:unclaimed` (Array<String>)
         def match_aggregates(held_shapes, current_shapes)
-          pairs = {}
-          current_shapes.each_key { |name| pairs[name] = held_shapes.key?(name) ? name : nil }
-
+          pairs = current_shapes.keys.to_h { |name| [name, held_shapes.key?(name) ? name : nil] }
           vanished = held_shapes.keys - current_shapes.keys
           appeared = current_shapes.keys.select { |name| pairs[name].nil? }
+          unclaimed = claim_renamed!(vanished, appeared, pairs, held_shapes, current_shapes)
+
+          retired = appeared.empty? ? unclaimed : []
+          { pairs: pairs, retired: retired, unclaimed: retired.empty? ? unclaimed : [] }
+        end
+
+        # Pairs each vanished aggregate with the one appeared aggregate sharing its full shape,
+        # mutating `pairs` and `appeared`; returns the vanished names left without a successor.
+        def claim_renamed!(vanished, appeared, pairs, held_shapes, current_shapes)
           unclaimed = []
           vanished.each do |old_name|
             old_shape = held_shapes[old_name].merge("name" => nil)
             candidates = appeared.select { |name| current_shapes[name].merge("name" => nil) == old_shape }
-            if candidates.size == 1
-              pairs[candidates.first] = old_name
-              appeared -= candidates
-            else
-              unclaimed << old_name
-            end
-          end
+            next unclaimed << old_name unless candidates.size == 1
 
-          retired = appeared.empty? ? unclaimed : []
-          { pairs: pairs, retired: retired, unclaimed: retired.empty? ? unclaimed : [] }
+            pairs[candidates.first] = old_name
+            appeared.delete(candidates.first)
+          end
+          unclaimed
         end
 
         # Resolves every changed path in one aggregate into rules by signature matching:
@@ -76,12 +87,9 @@ module Hecks
         # @return [Array<Hash{Symbol => Object}>] one rule per changed path (see
         #   `Renderer#render_rule`); `[]` when nothing changed
         def attribute_rules(held_shape, current_shape)
-          rules = []
-          rules << identity_hint(held_shape, current_shape)
-          rules.compact!
-          held_attrs = (held_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
-          current_attrs = (current_shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
-
+          held_attrs = attributes_by_name(held_shape)
+          current_attrs = attributes_by_name(current_shape)
+          rules = [identity_hint(held_shape, current_shape)].compact
           rules.concat(retype_rules(held_attrs, current_attrs))
           retyped = rules.filter_map { |rule| rule[:from] if rule[:kind] == :retype }
 
@@ -94,79 +102,50 @@ module Hecks
           rules
         end
 
+        # A shape's attributes keyed by name.
+        def attributes_by_name(shape)
+          (shape["attributes"] || []).to_h { |attribute| [attribute["name"], attribute] }
+        end
+
         # Retype rules for attributes whose members are unchanged but whose type name changed.
         def retype_rules(held_attrs, current_attrs)
           (held_attrs.keys & current_attrs.keys).filter_map do |name|
             held = held_attrs[name]
             current = current_attrs[name]
-            next if held == current
-            next unless container?(held) && container?(current)
-            next unless held["type"]["members"] == current["type"]["members"] && held["list"] == current["list"]
-
-            { kind: :retype, from: held["type"]["type"], to: current["type"]["type"] }
+            { kind: :retype, from: held["type"]["type"], to: current["type"]["type"] } if retyped?(held, current)
           end
         end
 
+        # Whether two versions of an attribute differ only in the name of the same-shaped type.
+        def retyped?(held, current)
+          held != current && container?(held) && container?(current) &&
+            held["type"]["members"] == current["type"]["members"] && held["list"] == current["list"]
+        end
+
         # Resolves each vanished path into a rename, move or unresolved rule appended to `rules`.
         def resolve_vanished_rules!(rules, vanished, appeared)
           vanished.each do |path, signature|
-            matches = appeared.select { |_, candidate| candidate == signature }.keys
-            taken = rules.filter_map { |rule| rule[:to] if %i[rename move].include?(rule[:kind]) }
-            matches -= taken
-            if matches.size == 1 && vanished.one? { |_, other| other == signature }
-              target = matches.first
-              kind = path.include?(".") || target.include?(".") ? :move : :rename
-              rules << { kind: kind, from: path, to: target }
-            else
-              candidates = matches.empty? ? compatible_candidates(appeared, signature) : matches
-              rules << { kind: :unresolved, from: path, candidates: candidates }
-            end
+            rules << rule_for(rules, path, signature, vanished, appeared)
           end
         end
 
-        # Held paths that need explaining: vanished attributes, and members that vanished or
-        # changed type inside a kept attribute — the set EraGuard demands coverage for.
-        # Returns each path (dotted for a member) valued by its type signature.
-        def vanished_paths(held_attrs, current_attrs, retyped)
-          paths = {}
-          held_attrs.each do |name, held|
-            next if retyped.include?(container?(held) ? held["type"]["type"] : nil)
-
-            current = current_attrs[name]
-            if current.nil?
-              paths[name] = held["type"]
-              next
-            end
-            next if held == current
-
-            held_members = members_of(held)
-            current_members = members_of(current)
-            held_members.each do |member, signature|
-              paths["#{name}.#{member}"] = signature if current_members[member] != signature
-            end
+        # The one rule a vanished path resolves to, given the targets earlier rules claimed.
+        def rule_for(rules, path, signature, vanished, appeared)
+          matches = appeared.select { |_, candidate| candidate == signature }.keys - claimed_targets(rules)
+          if matches.size == 1 && vanished.one? { |_, other| other == signature }
+            { kind: move_or_rename(path, matches.first), from: path, to: matches.first }
+          else
+            candidates = matches.empty? ? compatible_candidates(appeared, signature) : matches
+            { kind: :unresolved, from: path, candidates: candidates }
           end
-          paths
         end
 
-        # Current paths that need explaining; the mirror of `vanished_paths`.
-        def appeared_paths(held_attrs, current_attrs, retyped)
-          paths = {}
-          current_attrs.each do |name, current|
-            next if retyped.include?(container?(current) ? current["type"]["type"] : nil)
+        # A path crossing a value-object boundary on either end is a move; two bare names a rename.
+        def move_or_rename(path, target) = path.include?(".") || target.include?(".") ? :move : :rename
 
-            held = held_attrs[name]
-            if held.nil?
-              paths[name] = current["type"]
-              next
-            end
-            next if held == current
-
-            held_members = members_of(held)
-            members_of(current).each do |member, signature|
-              paths["#{name}.#{member}"] = signature if held_members[member] != signature
-            end
-          end
-          paths
+        # The destinations the rename and move rules so far already took.
+        def claimed_targets(rules)
+          rules.filter_map { |rule| rule[:to] if %i[rename move].include?(rule[:kind]) }
         end
 
         # An unresolved placeholder when the identity paths differ; nil when they match.
@@ -176,24 +155,6 @@ module Hecks
 
           { kind: :unresolved, from: :identity, candidates: [] }
         end
-
-        # Appeared paths type-compatible with a vanished path's signature.
-        def compatible_candidates(appeared, signature)
-          appeared.select { |_, candidate| scalar_of(candidate) == scalar_of(signature) }.keys
-        end
-
-        # Reduces a type signature to what `compatible_candidates` compares: members or the scalar.
-        def scalar_of(signature) = signature.is_a?(Hash) ? signature["members"] : signature
-
-        # A container attribute's members keyed by name; `{}` for a scalar.
-        def members_of(attribute)
-          return {} unless container?(attribute)
-
-          attribute["type"]["members"].to_h { |member| [member["name"], member["type"]] }
-        end
-
-        # Whether the attribute's type is a container (value object or entity), not a scalar.
-        def container?(attribute) = attribute["type"].is_a?(Hash)
       end
     end
   end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/path_diff.rb

@@ -0,0 +1,57 @@
+module Hecks
+  module Translation
+    module Scaffold
+      # The path-level half of `Differ`: which held and current attribute paths need explaining,
+      # and how a type signature is compared.
+      module PathDiff
+        # Held paths that need explaining: vanished attributes, and members that vanished or
+        # changed type inside a kept attribute — the set EraGuard demands coverage for.
+        # Returns each path (dotted for a member) valued by its type signature.
+        def vanished_paths(held_attrs, current_attrs, retyped) = unmatched_paths(held_attrs, current_attrs, retyped)
+
+        # Current paths that need explaining; the mirror of `vanished_paths`.
+        def appeared_paths(held_attrs, current_attrs, retyped) = unmatched_paths(current_attrs, held_attrs, retyped)
+
+        # Appeared paths type-compatible with a vanished path's signature.
+        def compatible_candidates(appeared, signature)
+          appeared.select { |_, candidate| scalar_of(candidate) == scalar_of(signature) }.keys
+        end
+
+        # Reduces a type signature to what `compatible_candidates` compares: members or the scalar.
+        def scalar_of(signature) = signature.is_a?(Hash) ? signature["members"] : signature
+
+        # A container attribute's members keyed by name; `{}` for a scalar.
+        def members_of(attribute)
+          return {} unless container?(attribute)
+
+          attribute["type"]["members"].to_h { |member| [member["name"], member["type"]] }
+        end
+
+        # Whether the attribute's type is a container (value object or entity), not a scalar.
+        def container?(attribute) = attribute["type"].is_a?(Hash)
+
+        # Paths in `attrs` that `others` lacks or holds differently: a whole attribute with no
+        # counterpart, or each member of a kept attribute that vanished or changed type.
+        def unmatched_paths(attrs, others, retyped)
+          attrs.each_with_object({}) do |(name, attribute), paths|
+            next if retyped.include?(container?(attribute) ? attribute["type"]["type"] : nil)
+
+            other = others[name]
+            if other.nil?
+              paths[name] = attribute["type"]
+            elsif attribute != other
+              paths.merge!(member_drift(name, attribute, other))
+            end
+          end
+        end
+
+        # The dotted member paths of `attribute` that `other` lacks or types differently.
+        def member_drift(name, attribute, other)
+          other_members = members_of(other)
+          members_of(attribute).reject { |member, signature| other_members[member] == signature }
+                               .transform_keys { |member| "#{name}.#{member}" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/renderer.rb

@@ -9,19 +9,25 @@ module Hecks
         # @param edge [Scaffold::Edge] the edge to render
         # @return [String] the `.bluebook` text, ending in a newline
         def render(edge)
-          lines = ["Hecks.data_translation #{edge.domain.inspect}, from: #{edge.from.inspect}, to: #{edge.to.inspect} do"]
-          edge.aggregates.each do |aggregate|
-            header = "  aggregate #{aggregate.name.inspect}"
-            header += ", was: #{aggregate.was.inspect}" if aggregate.was
-            lines << "#{header} do"
-            aggregate.rules.each { |rule| lines << "    #{render_rule(rule)}" } unless aggregate.rules.empty?
-            lines << "  end"
-          end
+          lines = [render_header(edge)]
+          edge.aggregates.each { |aggregate| lines.concat(render_aggregate(aggregate)) }
           edge.retired.each { |name| lines << "  retired #{name.inspect}" }
           lines << "end"
           "#{lines.join("\n")}\n"
         end
 
+        # Renders the line opening the edge's translation block.
+        def render_header(edge)
+          "Hecks.data_translation #{edge.domain.inspect}, from: #{edge.from.inspect}, to: #{edge.to.inspect} do"
+        end
+
+        # Renders one aggregate's block as lines.
+        def render_aggregate(aggregate)
+          header = "  aggregate #{aggregate.name.inspect}"
+          header += ", was: #{aggregate.was.inspect}" if aggregate.was
+          ["#{header} do", *aggregate.rules.map { |rule| "    #{render_rule(rule)}" }, "  end"]
+        end
+
         # Renders one scaffolded rule as a line of `.bluebook` source.
         #
         # @param rule [Hash{Symbol => Object}] a rule as `Differ#attribute_rules` builds it
@@ -31,12 +37,16 @@ module Hecks
           when :rename then "rename :#{rule[:from]}, to: :#{rule[:to]}"
           when :move then "move #{rule[:from].inspect}, to: #{rule[:to].inspect}"
           when :retype then "retype #{rule[:from].inspect}, to: #{rule[:to].inspect}"
-          when :unresolved
-            candidates = rule[:candidates].map { |candidate| render_path(candidate) }.join(", ")
-            "unresolved #{render_path(rule[:from])}, candidates: [#{candidates}]"
+          when :unresolved then render_unresolved(rule)
           end
         end
 
+        # Renders an ambiguity as an `unresolved` construct listing its candidate paths.
+        def render_unresolved(rule)
+          candidates = rule[:candidates].map { |candidate| render_path(candidate) }.join(", ")
+          "unresolved #{render_path(rule[:from])}, candidates: [#{candidates}]"
+        end
+
         # Renders a bare path as a Symbol literal and a dotted path as a String literal.
         def render_path(path) = path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
       end

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/writer.rb

@@ -16,14 +16,23 @@ module Hecks
           translations_dir = File.join(directory, "translations")
           FileUtils.mkdir_p(translations_dir)
 
-          existing = Dir[File.join(translations_dir, "*.bluebook")].find do |path|
-            text = File.read(path)
-            text.include?("from: #{edge.from.inspect}") && text.include?("to: #{edge.to.inspect}")
-          end
+          existing = existing_file(translations_dir, edge)
           path = existing || File.join(translations_dir, "#{edge.ordinal}-#{edge.label}.bluebook")
           File.write(path, render(edge))
           path
         end
+
+        # Finds a file already written for this shape pair, matched on its text.
+        #
+        # @param translations_dir [String] the directory holding the domain's translations
+        # @param edge [Scaffold::Edge] the edge whose `from:` and `to:` are looked for
+        # @return [String, nil] the matching path, or nil
+        def existing_file(translations_dir, edge)
+          Dir[File.join(translations_dir, "*.bluebook")].find do |path|
+            text = File.read(path)
+            text.include?("from: #{edge.from.inspect}") && text.include?("to: #{edge.to.inspect}")
+          end
+        end
       end
     end
   end