hecks 3.5.0 → 3.6.0

data/lib/hecks/fuzzing/domain_generator/builder/wiring.rb

@@ -0,0 +1,128 @@
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      class Builder
+        # What links aggregates to each other: references, chains, policies, roles, and the extras
+        # sprinkled over every aggregate.
+        module Wiring
+          # Each extra shape and the probability an aggregate gets it, in the order they are drawn.
+          EXTRA_SHAPES = [[:lifecycle, 0.4], [:closed_set, 0.25], [:default_attr, 0.25], [:optional_arg, 0.25],
+                          [:entity, 0.2], [:query, 0.3]].freeze
+
+          private
+
+          def reference_attr(owner, target)
+            return unless target
+            return if owner["references"].include?(target["name"])
+
+            open = creating(owner)
+            add_reference!(owner, open, target)
+            open["givens"] << open_given(owner, target) if target["lifecycle"] && chance?(0.5)
+          end
+
+          def add_reference!(owner, open, target)
+            owner["references"] << target["name"]
+            open["references"] << target["name"]
+            open["sets"] << { "target"   => snake(target["name"]),
+                              "requires" => ["reference:#{owner["name"]}->#{target["name"]}"] }
+          end
+
+          # A given that the referenced aggregate is open.
+          def open_given(owner, target)
+            { "label"    => "the #{snake(target["name"])} is open",
+              "expr"     => "#{snake(target["name"])}.status == \"open\"",
+              "requires" => ["lifecycle:#{target["name"]}",
+                             "command_reference:#{owner["name"]}.Open->#{target["name"]}"] }
+          end
+
+          # `chain` is ordered primary, middle, root — root gets the lifecycle.
+          def link_chain(chain)
+            primary, middle, root = chain
+            lifecycle(root)
+            reference_attr(middle, root)
+            reference_attr(primary, middle)
+          end
+
+          def two_hop_given(primary, middle, root)
+            return unless middle && root
+
+            path = "#{snake(middle["name"])}.#{snake(root["name"])}.status"
+            creating(primary)["givens"] << {
+              "label" => "the #{snake(middle["name"])}'s #{snake(root["name"])} is open", "expr" => "#{path} == \"open\"",
+              "requires" => ["lifecycle:#{root["name"]}", "reference:#{middle["name"]}->#{root["name"]}",
+                             "command_reference:#{primary["name"]}.Open->#{middle["name"]}"]
+            }
+          end
+
+          def multi_hop_where(primary, middle, root)
+            return unless middle && root
+
+            field = "#{snake(middle["name"])}/#{snake(root["name"])}/status"
+            primary["queries"] << {
+              "name" => "ThroughOpen#{root["name"]}", "order_by" => primary["identity"].first,
+              "wheres" => [{ "field" => field, "value" => "open",
+                             "requires" => ["lifecycle:#{root["name"]}", "reference:#{middle["name"]}->#{root["name"]}",
+                                            "reference:#{primary["name"]}->#{middle["name"]}"] }]
+            }
+          end
+
+          # Mirrors `Referral.Reassign` (ADR 0037 F5): redeclares the reference
+          # under a plain value object instead of the reference itself.
+          def revalued_reference(owner, target)
+            return unless target
+
+            reference_attr(owner, target)
+            field = snake(target["name"])
+            vo(owner, "#{target["name"]}Handle", "string")
+            requires = ["reference:#{owner["name"]}->#{target["name"]}"]
+            command(owner, "Repoint", args: [{ "name" => field, "type" => "#{target["name"]}Handle" }],
+                                      sets: [{ "target" => field, "requires" => requires }])
+          end
+
+          def extras(aggregate, aggregates)
+            extra_shape(aggregate)
+            extra_wiring(aggregate, aggregates)
+          end
+
+          def extra_shape(aggregate)
+            EXTRA_SHAPES.each { |shape, probability| send(shape, aggregate) if chance?(probability) }
+            emits = creating(aggregate)["emits"]
+            emits << "#{aggregate["name"]}Logged" if chance?(0.15) && emits.size == 1
+          end
+
+          def extra_wiring(aggregate, aggregates)
+            other = (aggregates - [aggregate]).sample(random: @random)
+            reference_attr(aggregate, other) if other && chance?(0.15) && !creates_cycle?(aggregate, other, aggregates)
+            assign_roles(aggregate)
+            policy(aggregate) if aggregate["lifecycle"] && chance?(0.25)
+          end
+
+          # Each command has a 30% chance of being role-gated, with a drawn role.
+          def assign_roles(aggregate)
+            aggregate["commands"].each { |command| command["role"] = ROLES.sample(random: @random) if chance?(0.3) }
+          end
+
+          def creates_cycle?(from, to, aggregates)
+            seen = Set.new
+            stack = [to["name"]]
+            until stack.empty?
+              name = stack.pop
+              return true if name == from["name"]
+              next unless seen.add?(name)
+
+              stack.concat(aggregates.find { |aggregate| aggregate["name"] == name }["references"])
+            end
+            false
+          end
+
+          def policy(aggregate)
+            name = aggregate["name"]
+            event = creating(aggregate)["emits"].first
+            @policies << { "name" => "On#{event}Close", "on" => "#{name}::#{event}", "trigger" => "#{name}::Close",
+                           "requires" => ["event:#{name}.#{event}", "command:#{name}.Close", "lifecycle:#{name}"] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/domain_generator/builder.rb

@@ -0,0 +1,105 @@
+require_relative "builder/attribute_shapes"
+require_relative "builder/shapes"
+require_relative "builder/wiring"
+
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      # One seeded pass: builds the aggregates the forced forms need, applies
+      # each form to the primary aggregate, then sprinkles extras everywhere.
+      class Builder
+        include AttributeShapes
+        include Shapes
+        include Wiring
+
+        def initialize(random, forms)
+          @random = random
+          @forms  = forms
+          @names  = AGGREGATE_NAMES.shuffle(random: random)
+          @policies = []
+        end
+
+        def build
+          chain = @forms.intersect?(CHAIN_FORMS)
+          aggregates = @names.first(aggregate_count(chain)).map { |name| base(name) }
+          primary = aggregates.first
+
+          link_chain(aggregates.first(3)) if chain
+          @forms.each { |form| apply_form(form, primary, aggregates) }
+          aggregates.each { |aggregate| extras(aggregate, aggregates) }
+          { "aggregates" => aggregates, "policies" => @policies }
+        end
+
+        FORM_STEPS = {
+          "composite_id"       => ->(primary, _) { composite_id(primary) },
+          "has_entity"         => ->(primary, _) { entity(primary) },
+          "two_entities"       => ->(primary, _) { 2.times { entity(primary) } },
+          "composite_piece"    => ->(primary, _) { entity(primary, composite: true) },
+          "multi_emit"         => ->(primary, _) { creating(primary)["emits"] << "#{primary["name"]}Logged" },
+          "lifecycle"          => ->(primary, _) { lifecycle(primary) },
+          "piece_lifecycle"    => ->(primary, _) { entity(primary, lifecycle: true) },
+          "has_query"          => ->(primary, _) { query(primary) },
+          "list_attr"          => ->(primary, _) { list_attr(primary) },
+          "reference_attr"     => ->(primary, all) { reference_attr(primary, all[1]) },
+          "closed_set"         => ->(primary, _) { closed_set(primary) },
+          "has_default"        => ->(primary, _) { default_attr(primary) },
+          "has_optional"       => ->(primary, _) { optional_arg(primary) },
+          "two_hop_given"      => ->(primary, all) { two_hop_given(primary, all[1], all[2]) },
+          "multi_hop_where"    => ->(primary, all) { multi_hop_where(primary, all[1], all[2]) },
+          "revalued_reference" => ->(primary, all) { revalued_reference(primary, all[1]) }
+        }.freeze
+
+        private
+
+        # How many aggregates the forms need, with a 30% chance of one more when under three.
+        def aggregate_count(chain)
+          count = if chain then 3
+                  elsif @forms.intersect?(REFERENCE_FORMS) then 2
+                  else 1
+                  end
+          count += 1 if count < 3 && @random.rand < 0.3
+          count
+        end
+
+        def chance?(probability) = @random.rand < probability
+
+        def base(name)
+          aggregate = { "name" => name, "identity" => ["code"], "vos" => {}, "attributes" => [], "references" => [],
+                        "lifecycle" => nil, "invariants" => [], "entities" => [], "commands" => [], "queries" => [] }
+          vo(aggregate, "#{name}Code", "string")
+          aggregate["attributes"] << { "name" => "code", "type" => "#{name}Code" }
+          aggregate["commands"] << { "name" => "Open", "creates" => true, "references" => [],
+                                     "args" => [{ "name" => "code", "type" => "#{name}Code" }],
+                                     "givens" => [], "sets" => [{ "target" => "code" }], "emits" => ["#{name}Opened"] }
+          aggregate
+        end
+
+        def vo(aggregate, name, kind, members: nil)
+          aggregate["vos"][name] ||= { "kind" => kind }.merge(members ? { "members" => members } : {})
+        end
+
+        def creating(aggregate) = aggregate["commands"].find { |command| command["creates"] }
+
+        # Adds the command `name` to the aggregate, unless it already has one. `parts` are the
+        # command's `args:`, `sets:`, `givens:` (default `[]`) and `emits:` (default: the
+        # aggregate's name and the past tense of the verb).
+        def command(aggregate, name, **parts)
+          existing = aggregate["commands"].find { |candidate| candidate["name"] == name }
+          return existing if existing
+
+          entry = { "name" => name, "creates" => false, "references" => [], "args" => parts.fetch(:args, []),
+                    "givens" => parts.fetch(:givens, []), "sets" => parts.fetch(:sets, []),
+                    "emits" => parts[:emits] || ["#{aggregate["name"]}#{past(name)}"] }
+          aggregate["commands"] << entry
+          entry
+        end
+
+        def past(verb) = verb.end_with?("e") ? "#{verb}d" : "#{verb}ed"
+
+        def apply_form(form, primary, aggregates) = instance_exec(primary, aggregates, &FORM_STEPS.fetch(form))
+
+        def snake(name) = DomainGenerator.snake(name)
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/domain_generator/pruning.rb

@@ -0,0 +1,90 @@
+require "json"
+require_relative "removals"
+require_relative "tokens"
+
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      # Shrinking a blueprint: the single removals that can be tried, and the pruning that drops
+      # whatever a removal left dangling.
+      module Pruning
+        include Removals
+        include Tokens
+
+        # Identity attributes and creating commands are never offered for
+        # removal — without them there is no domain left to dispatch against.
+        def shrink_candidates(blueprint)
+          removals(blueprint).map { |path| prune(remove_at(blueprint, path)) }.uniq.reject { |candidate| candidate == blueprint }
+        end
+
+        # Repeatedly drops whatever a removal left dangling, using each
+        # element's `requires` tokens — set arithmetic, never a re-read of
+        # the rendered source.
+        def prune(blueprint)
+          current = JSON.parse(JSON.generate(blueprint))
+          loop do
+            available = tokens(current)
+            before = JSON.generate(current)
+            prune_once!(current, available)
+            break if JSON.generate(current) == before
+          end
+          current
+        end
+
+        def prune_once!(blueprint, available)
+          keep = ->(item) { Array(item["requires"]).all? { |token| available.include?(token) } }
+          blueprint["policies"].select!(&keep)
+          blueprint["aggregates"].each { |aggregate| prune_aggregate!(aggregate, available, keep) }
+        end
+
+        def prune_aggregate!(aggregate, available, keep)
+          aggregate["references"].select! { |target| available.include?("aggregate:#{target}") }
+          %w[attributes invariants entities].each { |key| aggregate[key].select!(&keep) }
+          prune_queries!(aggregate, keep)
+          [aggregate, *aggregate["entities"]].each { |owner| prune_owner!(owner, available) }
+        end
+
+        def prune_queries!(aggregate, keep)
+          aggregate["queries"].each { |query| query["wheres"].select!(&keep) }
+          aggregate["queries"].select! { |query| query["wheres"].any? }
+        end
+
+        # The lifecycle and commands of an aggregate or one of its entities.
+        def prune_owner!(owner, available)
+          prune_lifecycle!(owner, available)
+          owner["commands"].each { |command| prune_command!(command, available) }
+        end
+
+        def prune_lifecycle!(owner, available)
+          return unless owner["lifecycle"]
+
+          transitions = owner["lifecycle"]["transitions"]
+          transitions.select! { |t| available.include?(t["requires"].first) }
+          reachable = reachable_states(owner["lifecycle"]["default"], transitions)
+          transitions.select! { |t| leaves_reached_state?(t, reachable) }
+          owner["lifecycle"] = nil if transitions.empty?
+        end
+
+        def leaves_reached_state?(transition, reachable) = transition["from"].any? { |state| reachable.include?(state) }
+
+        # A transition out of an unreached state can never fire; leaving one
+        # behind after a shrink is a dead transition `hecks model_check` reports.
+        def reachable_states(default, transitions)
+          reachable = [default]
+          loop do
+            reached = transitions.select { |t| leaves_reached_state?(t, reachable) }.map { |t| t["to"] }
+            return reachable if (reached - reachable).empty?
+
+            reachable |= reached
+          end
+        end
+
+        def prune_command!(command, available)
+          keep = ->(item) { Array(item["requires"]).all? { |token| available.include?(token) } }
+          command["references"].select! { |target| available.include?("aggregate:#{target}") }
+          %w[args givens sets].each { |key| command[key].select!(&keep) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/domain_generator/removals.rb

@@ -0,0 +1,62 @@
+require "json"
+
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      # The single removals a blueprint can be shrunk by.
+      module Removals
+        def removals(blueprint)
+          paths = blueprint["policies"].each_index.map { |i| ["policies", i] }
+          blueprint["aggregates"].each_with_index { |aggregate, a| paths.concat(aggregate_removals(aggregate, a)) }
+          paths
+        end
+
+        def aggregate_removals(aggregate, index)
+          at = ["aggregates", index]
+          paths = index.positive? ? [at] : []
+          paths.concat(member_removals(aggregate, at))
+          paths.concat(attribute_removals(aggregate, at))
+          aggregate["commands"].each_with_index { |command, i| paths.concat(command_removals(command, [*at, "commands", i])) }
+          paths.concat(entity_removals(aggregate, at))
+        end
+
+        # Each query, invariant, entity and reference, then the lifecycle.
+        def member_removals(aggregate, at)
+          paths = %w[queries invariants entities references].flat_map do |key|
+            aggregate[key].each_index.map { |i| [*at, key, i] }
+          end
+          aggregate["lifecycle"] ? paths << [*at, "lifecycle"] : paths
+        end
+
+        def attribute_removals(aggregate, at)
+          aggregate["attributes"].each_with_index.filter_map do |attribute, i|
+            [*at, "attributes", i] unless aggregate["identity"].include?(attribute["name"])
+          end
+        end
+
+        def entity_removals(aggregate, at)
+          aggregate["entities"].each_with_index.flat_map do |entity, e|
+            paths = entity["lifecycle"] ? [[*at, "entities", e, "lifecycle"]] : []
+            paths + entity["commands"].each_index.map { |i| [*at, "entities", e, "commands", i] }
+          end
+        end
+
+        def command_removals(command, at)
+          paths = command["creates"] ? [] : [at]
+          command["givens"].each_index { |g| paths << [*at, "givens", g] }
+          paths << [*at, "role"] if command["role"]
+          paths << [*at, "emits", command["emits"].size - 1] if command["emits"].size > 1
+          paths
+        end
+
+        def remove_at(blueprint, path)
+          copy = JSON.parse(JSON.generate(blueprint))
+          *parents, last = path
+          holder = parents.empty? ? copy : copy.dig(*parents)
+          holder.is_a?(Array) ? holder.delete_at(last) : holder.delete(last)
+          copy
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/domain_generator/rendering.rb

@@ -0,0 +1,94 @@
+require_relative "block_rendering"
+
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      # Renders a blueprint to bluebook source text.
+      module Rendering
+        include BlockRendering
+
+        def render(blueprint)
+          out = render_header(blueprint)
+          blueprint["aggregates"].each { |aggregate| out.concat(render_aggregate(aggregate)) }
+          blueprint["policies"].each { |policy| out.concat(render_policy(policy)) }
+          out << "end"
+          "#{out.join("\n")}\n"
+        end
+
+        def render_header(blueprint)
+          ["# GENERATED by Hecks::Fuzzing::DomainGenerator — seed #{blueprint["seed"]}, forms " \
+           "#{blueprint["forms"].join(", ")}. Not hand-written; see hecks quality_control check_generated_domains.",
+           "Hecks.bluebook #{DOMAIN_NAME.inspect} do",
+           "  vision #{"A generated domain that puts #{blueprint["forms"].join(" and ")} together.".inspect}",
+           "",
+           "  core"]
+        end
+
+        def render_aggregate(aggregate)
+          [*aggregate_header(aggregate), *aggregate_fields(aggregate), *aggregate_rules(aggregate),
+           *aggregate_behaviors(aggregate), "  end"]
+        end
+
+        def aggregate_header(aggregate)
+          ["", "  aggregate #{aggregate["name"].inspect} do",
+           "    description #{"A generated #{aggregate["name"].downcase}.".inspect}", "",
+           identity_line(aggregate["identity"], "    ")]
+        end
+
+        # An aggregate's attributes, references and value objects.
+        def aggregate_fields(aggregate)
+          aggregate["attributes"].map { |attribute| "    #{render_attribute(attribute)}" } +
+            aggregate["references"].map { |target| "    reference_to #{target}" } +
+            aggregate["vos"].flat_map { |name, vo| render_value_object(name, vo, "    ") }
+        end
+
+        # An aggregate's lifecycle and invariants.
+        def aggregate_rules(aggregate)
+          lifecycle = aggregate["lifecycle"] ? render_lifecycle(aggregate["lifecycle"], "    ") : []
+          lifecycle + aggregate["invariants"].map { |inv| "    invariant(#{inv["label"].inspect}) { #{inv["expr"]} }" }
+        end
+
+        # An aggregate's entities, commands and queries.
+        def aggregate_behaviors(aggregate)
+          aggregate["entities"].flat_map { |entity| render_entity(entity) } +
+            aggregate["commands"].flat_map { |command| render_command(command, aggregate["name"], "    ") } +
+            aggregate["queries"].flat_map { |query| render_query(query) }
+        end
+
+        def identity_line(identity, indent) = "#{indent}identified_by #{identity.map { |part| ":#{part}" }.join(", ")}"
+
+        def render_entity(entity)
+          lifecycle = entity["lifecycle"] ? render_lifecycle(entity["lifecycle"], "      ") : []
+          ["", "    entity #{entity["name"].inspect} do",
+           "      description #{"A generated #{entity["name"].downcase}.".inspect}",
+           identity_line(entity["identity"], "      "),
+           *entity["attributes"].map { |attribute| "      #{render_attribute(attribute)}" },
+           *lifecycle,
+           *entity["commands"].flat_map { |command| render_command(command, nil, "      ") },
+           "    end"]
+        end
+
+        def render_attribute(attribute)
+          type = attribute["list"] ? "list_of(#{attribute["type"]})" : attribute["type"]
+          line = "attribute :#{attribute["name"]}, #{type}"
+          line += ", optional: true" if attribute["optional"]
+          line += ", default: { value: #{attribute["default"].inspect} }" if attribute.key?("default")
+          line
+        end
+
+        def render_query(query)
+          out = ["", "    query #{query["name"].inspect} do", "      description #{"Generated #{query["name"]}.".inspect}"]
+          query["wheres"].each do |where|
+            out << "      where(:#{where["field"].inspect} => #{where["value"].inspect})"
+          end
+          out << "      order_by :#{query["order_by"]}"
+          out << "    end"
+        end
+
+        def render_policy(policy)
+          ["", "  policy #{policy["name"].inspect} do", "    on #{policy["on"]}", "    trigger #{policy["trigger"]}", "  end"]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/domain_generator/tokens.rb

@@ -0,0 +1,38 @@
+module Hecks
+  module Fuzzing
+    module DomainGenerator
+      # The tokens a blueprint offers, which each element's `requires` is checked against.
+      module Tokens
+        def tokens(blueprint)
+          blueprint["aggregates"].each_with_object(Set.new) { |aggregate, set| aggregate_tokens(aggregate, set) }
+        end
+
+        def aggregate_tokens(aggregate, set)
+          name = aggregate["name"]
+          set << "aggregate:#{name}"
+          set << "lifecycle:#{name}" if aggregate["lifecycle"]
+          aggregate["attributes"].each { |attribute| set << "attribute:#{name}.#{attribute["name"]}" }
+          aggregate["references"].each { |target| set << "reference:#{name}->#{target}" }
+          nested_tokens(name, aggregate, set)
+        end
+
+        def nested_tokens(name, aggregate, set)
+          aggregate["commands"].each { |command| command_tokens(name, command, set) }
+          aggregate["entities"].each { |entity| entity_tokens(name, entity, set) }
+        end
+
+        def command_tokens(name, command, set)
+          set << "command:#{name}.#{command["name"]}"
+          command["references"].each { |target| set << "command_reference:#{name}.#{command["name"]}->#{target}" }
+          command["emits"].each { |event| set << "event:#{name}.#{event}" }
+        end
+
+        def entity_tokens(name, entity, set)
+          set << "entity:#{name}.#{entity["name"]}"
+          set << "lifecycle:#{name}.#{entity["name"]}" if entity["lifecycle"]
+          entity["commands"].each { |command| set << "command:#{name}.#{entity["name"]}.#{command["name"]}" }
+        end
+      end
+    end
+  end
+end