hecks 1.4.0 → 1.5.0

data/lib/hecks/fuzzing/domain_generator.rb

@@ -7,6 +7,8 @@ module Hecks
     # A small, valid bluebook, written from a seed — so the QA loop can test
     # construct combinations nobody has hand-authored yet.
     #
+    # ## Why this exists
+    #
     # The ledger's most productive moments were a new stress domain's first
     # sweep: `corrections` found four bugs, `referral_chain` four,
     # `tenant_ledger` two. Every one of those domains was written by hand,
@@ -20,14 +22,17 @@ module Hecks
     # policy, a role), and renders the whole thing as ordinary bluebook
     # source any runtime boots.
     #
-    # A blueprint, not source, is the unit. `generate` answers a plain,
-    # JSON-shaped Hash (string keys) — a small IR of its own — and `render`
-    # turns it into source. That split is what makes a finding shrinkable
-    # at the domain level: `shrink_candidates` removes one element at a time
-    # (a query, a command, an entity, an aggregate, a given…) and `prune`
-    # drops whatever that removal left dangling, using the explicit
-    # `requires` tokens every dependent element carries. Nothing here
-    # parses Ruby back.
+    # ## Blueprint, not source, is the unit
+    #
+    # `generate` answers a plain, JSON-shaped Hash (string keys) — a small
+    # IR of its own — and `render` turns it into source. That split is what
+    # makes a finding shrinkable at the domain level: `shrink_candidates`
+    # removes one element at a time (a query, a command, an entity, an
+    # aggregate, a given…) and `prune` drops whatever that removal left
+    # dangling, using the explicit `requires` tokens every dependent
+    # element carries. Nothing here parses Ruby back.
+    #
+    # ## One fixed domain name
     #
     # Every generated domain is the same domain name — `QaGenerated`, in a
     # `qa_generated/bluebook/qa_generated.bluebook` directory — because the
@@ -60,6 +65,16 @@ module Hecks
 
       module_function
 
+      # Builds a random blueprint from a seed and prunes it to a fixpoint,
+      # ready for `write` to render into a fresh `QaGenerated` domain.
+      #
+      # @param seed [Integer] the random seed; the same seed and `forms` always
+      #   produce the same blueprint
+      # @param forms [Array<String, Symbol>, nil] the `FormCensus::FORMS` names to
+      #   force onto the primary aggregate; two random forms from `FORMS` when nil
+      # @return [Hash{String => Object}] the pruned blueprint, with `"seed"` and
+      #   `"forms"` merged in
+      # @raise [ArgumentError] if `forms` names anything outside `FORMS`
       def generate(seed:, forms: nil)
         random = Random.new(seed)
         forms  = Array(forms || FORMS.sample(2, random: random)).map(&:to_s)
@@ -77,6 +92,11 @@ module Hecks
       # A blueprint carrying `"source"` is bluebook text someone else wrote
       # (`bin/qa_mine_combinations`' agent): it is adopted, not rendered,
       # and its empty `aggregates`/`policies` leave nothing to shrink.
+      #
+      # @param blueprint [Hash{String => Object}] a blueprint as `generate` answers,
+      #   or one carrying a `"source"` key instead of `"aggregates"`/`"policies"`
+      # @param root [String] the directory to write the domain and blueprint under
+      # @return [String] the written domain's directory (`<root>/qa_generated`)
       def write(blueprint, root)
         domain = File.join(root, DIRECTORY)
         FileUtils.rm_rf(domain)
@@ -89,12 +109,21 @@ module Hecks
 
       # Renames an outside bluebook's own chapter to `QaGenerated`, the one
       # name the scratch crate and child processes are built around.
+      #
+      # @param source [String] bluebook source text declaring one chapter
+      # @return [String] `source` with its `Hecks.bluebook "..."` chapter name
+      #   replaced by `"QaGenerated"`
       def adopt(source)
         source.sub(/Hecks\.bluebook\s*\(?\s*(["'])[^"']+\1/) { "Hecks.bluebook #{DOMAIN_NAME.inspect}" }
       end
 
       # ── rendering ───────────────────────────────────────────────────
 
+      # Renders a whole blueprint into one bluebook source file.
+      #
+      # @param blueprint [Hash{String => Object}] a blueprint as `generate` answers
+      # @return [String] the complete `Hecks.bluebook "QaGenerated" do ... end` source,
+      #   ending in a newline
       def render(blueprint)
         out = []
         out << "# GENERATED by Hecks::Fuzzing::DomainGenerator — seed #{blueprint['seed']}, forms " \
@@ -109,6 +138,11 @@ module Hecks
         "#{out.join("\n")}\n"
       end
 
+      # Renders one aggregate's whole `aggregate ... end` block, including
+      # every value object, entity, command and query it declares.
+      #
+      # @param aggregate [Hash{String => Object}] one aggregate's blueprint entry
+      # @return [Array<String>] source lines, unindented at the block's own `aggregate`/`end`
       def render_aggregate(aggregate)
         out = aggregate_header(aggregate)
         aggregate["attributes"].each { |attribute| out << "    #{render_attribute(attribute)}" }
@@ -122,12 +156,22 @@ module Hecks
         out << "  end"
       end
 
+      # Renders an aggregate block's opening lines, up through `identified_by`.
+      #
+      # @param aggregate [Hash{String => Object}] one aggregate's blueprint entry
+      # @return [Array<String>] the `aggregate ... do`, `description` and
+      #   `identified_by` lines
       def aggregate_header(aggregate)
         ["", "  aggregate #{aggregate['name'].inspect} do",
          "    description #{"A generated #{aggregate['name'].downcase}.".inspect}", "",
          "    identified_by #{aggregate['identity'].map { |part| ":#{part}" }.join(', ')}"]
       end
 
+      # Renders one entity's whole `entity ... end` block.
+      #
+      # @param entity [Hash{String => Object}] one entity's blueprint entry, as built
+      #   by `Builder#entity`
+      # @return [Array<String>] source lines, unindented at the block's own `entity`/`end`
       def render_entity(entity)
         out = ["", "    entity #{entity['name'].inspect} do",
                "      description #{"A generated #{entity['name'].downcase}.".inspect}"]
@@ -138,6 +182,12 @@ module Hecks
         out << "    end"
       end
 
+      # Renders one `attribute` declaration line.
+      #
+      # @param attribute [Hash{String => Object}] `"name"`, `"type"`, and optional
+      #   `"list"`, `"optional"`, `"default"` keys
+      # @return [String] one `attribute :name, Type` line, with `list_of`, `optional:`
+      #   and `default:` added as the Hash calls for
       def render_attribute(attribute)
         type = attribute["list"] ? "list_of(#{attribute['type']})" : attribute["type"]
         line = "attribute :#{attribute['name']}, #{type}"
@@ -146,6 +196,13 @@ module Hecks
         line
       end
 
+      # Renders one `value_object ... end` block.
+      #
+      # @param name [String] the value object's declared name
+      # @param value_object [Hash{String => Object}] `"kind"` (`"string"`, `"positive"`,
+      #   `"integer"` or `"closed"`) and, for `"closed"`, a `"members"` array
+      # @param indent [String] leading whitespace for every rendered line
+      # @return [Array<String>] source lines, indented by `indent`
       def render_value_object(name, value_object, indent)
         body =
           case value_object["kind"]
@@ -162,6 +219,12 @@ module Hecks
         ["", "#{indent}value_object #{name.inspect} do", *body.map { |line| "#{indent}  #{line}" }, "#{indent}end"]
       end
 
+      # Renders one `lifecycle ... end` block.
+      #
+      # @param lifecycle [Hash{String => Object}] `"field"`, `"default"` and
+      #   `"transitions"` (each `"command"`, `"to"`, `"from"`)
+      # @param indent [String] leading whitespace for every rendered line
+      # @return [Array<String>] source lines, indented by `indent`
       def render_lifecycle(lifecycle, indent)
         out = ["", "#{indent}lifecycle :#{lifecycle['field']}, default: #{lifecycle['default'].inspect} do"]
         lifecycle["transitions"].each do |transition|
@@ -171,6 +234,15 @@ module Hecks
         out << "#{indent}end"
       end
 
+      # Renders one `command ... end` block.
+      #
+      # @param command [Hash{String => Object}] `"name"`, `"creates"`, `"role"`,
+      #   `"references"`, `"args"`, `"givens"`, `"sets"` and `"emits"`
+      # @param self_name [String, nil] the owning aggregate's name, added as a
+      #   `reference_to` on a non-creating entity command; nil for an
+      #   aggregate-level command, which needs no reference to itself
+      # @param indent [String] leading whitespace for every rendered line
+      # @return [Array<String>] source lines, indented by `indent`
       def render_command(command, self_name, indent)
         out = ["", "#{indent}command #{command['name'].inspect} do"]
         out << "#{indent}  role #{command['role'].inspect}" if command["role"]
@@ -184,6 +256,12 @@ module Hecks
         out << "#{indent}end"
       end
 
+      # Renders one `sets` line inside a command block.
+      #
+      # @param set [Hash{String => Object}] `"target"`, plus either `"to"` (rename) or
+      #   `"append"` (a Hash of field => value token to append with); neither means a
+      #   bare positional set
+      # @return [String] one `sets :target[, to: :value | append: { ... }]` line
       def render_set(set)
         return "sets :#{set['target']}, to: :#{set['to']}" if set["to"]
         return "sets :#{set['target']}, append: { #{set['append'].map { |k, v| "#{k}: :#{v}" }.join(', ')} }" if set["append"]
@@ -191,6 +269,11 @@ module Hecks
         "sets :#{set['target']}"
       end
 
+      # Renders one `query ... end` block.
+      #
+      # @param query [Hash{String => Object}] `"name"`, `"wheres"` (each `"field"`,
+      #   `"value"`) and `"order_by"`
+      # @return [Array<String>] source lines, unindented at the block's own `query`/`end`
       def render_query(query)
         out = ["", "    query #{query['name'].inspect} do", "      description #{"Generated #{query['name']}.".inspect}"]
         query["wheres"].each do |where|
@@ -200,6 +283,10 @@ module Hecks
         out << "    end"
       end
 
+      # Renders one `policy ... end` block.
+      #
+      # @param policy [Hash{String => Object}] `"name"`, `"on"` and `"trigger"`
+      # @return [Array<String>] source lines, unindented at the block's own `policy`/`end`
       def render_policy(policy)
         ["", "  policy #{policy['name'].inspect} do", "    on #{policy['on']}", "    trigger #{policy['trigger']}", "  end"]
       end
@@ -209,10 +296,19 @@ module Hecks
       # Every blueprint one removal smaller, each already pruned. Identity
       # attributes and creating commands are never offered: without them
       # there is no domain left to dispatch against.
+      #
+      # @param blueprint [Hash{String => Object}] a blueprint as `generate` answers
+      # @return [Array<Hash{String => Object}>] one pruned blueprint per candidate removal,
+      #   deduplicated and never including `blueprint` itself
       def shrink_candidates(blueprint)
         removals(blueprint).map { |path| prune(remove_at(blueprint, path)) }.uniq.reject { |candidate| candidate == blueprint }
       end
 
+      # Every path into `blueprint` naming one element a shrink could remove.
+      #
+      # @param blueprint [Hash{String => Object}] a blueprint as `generate` answers
+      # @return [Array<Array<String, Integer>>] one path per removable element, each
+      #   a sequence of Hash keys and Array indices `Hash#dig` can follow
       def removals(blueprint)
         paths = blueprint["policies"].each_index.map { |i| ["policies", i] }
         blueprint["aggregates"].each_with_index do |aggregate, a|
@@ -229,6 +325,12 @@ module Hecks
         paths
       end
 
+      # `removals`'s own entity half — one path per entity's lifecycle (if any) and
+      # per entity command.
+      #
+      # @param aggregate [Hash{String => Object}] one aggregate's blueprint entry
+      # @param at [Array<String, Integer>] the path prefix to `aggregate` itself
+      # @return [Array<Array<String, Integer>>] one path per removable entity element
       def entity_removals(aggregate, at)
         aggregate["entities"].each_with_index.flat_map do |entity, e|
           paths = entity["lifecycle"] ? [[*at, "entities", e, "lifecycle"]] : []
@@ -236,6 +338,13 @@ module Hecks
         end
       end
 
+      # `removals`'s own command half — one path for the whole command (unless it
+      # creates the aggregate), one per given, and one for its role or its last
+      # extra emit.
+      #
+      # @param command [Hash{String => Object}] one command's blueprint entry
+      # @param at [Array<String, Integer>] the path prefix to `command` itself
+      # @return [Array<Array<String, Integer>>] one path per removable command element
       def command_removals(command, at)
         paths = command["creates"] ? [] : [at]
         command["givens"].each_index { |g| paths << [*at, "givens", g] }
@@ -244,6 +353,13 @@ module Hecks
         paths
       end
 
+      # Deep-copies `blueprint` and deletes whatever `path` names.
+      #
+      # @param blueprint [Hash{String => Object}] a blueprint as `generate` answers
+      # @param path [Array<String, Integer>] a path as `removals` returns, its last
+      #   element the Hash key or Array index to delete
+      # @return [Hash{String => Object}] a deep copy of `blueprint` with that one
+      #   element removed
       def remove_at(blueprint, path)
         copy = JSON.parse(JSON.generate(blueprint))
         *parents, last = path
@@ -257,6 +373,11 @@ module Hecks
       # what must still exist (`attribute:Ticket.score`, `lifecycle:Desk`,
       # `reference:Ticket->Desk`, `command:Ticket.Close`, …) — so this is
       # set arithmetic over those tokens, never a reading of the source.
+      #
+      # @param blueprint [Hash{String => Object}] a blueprint as `generate` answers
+      # @return [Hash{String => Object}] a deep copy of `blueprint` with every element
+      #   whose `requires` tokens are not all still present removed, repeated until
+      #   nothing more can be dropped
       def prune(blueprint)
         current = JSON.parse(JSON.generate(blueprint))
         loop do
@@ -268,12 +389,28 @@ module Hecks
         current
       end
 
+      # One pass of `prune` — drops every policy, then every aggregate element,
+      # whose `requires` tokens are not all in `available`.
+      #
+      # @param blueprint [Hash{String => Object}] the blueprint being pruned, mutated
+      #   in place
+      # @param available [Set<String>] every token `tokens` finds still declared
+      # @return [void]
       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
 
+      # `prune_once!`'s own per-aggregate pass — drops attributes, invariants,
+      # entities, unsatisfied references and empty queries, then recurses into
+      # each remaining lifecycle and command.
+      #
+      # @param aggregate [Hash{String => Object}] one aggregate's blueprint entry,
+      #   mutated in place
+      # @param available [Set<String>] every token `tokens` finds still declared
+      # @param keep [Proc] the `requires`-satisfied predicate `prune_once!` built
+      # @return [void]
       def prune_aggregate!(aggregate, available, keep)
         aggregate["references"].select! { |target| available.include?("aggregate:#{target}") }
         %w[attributes invariants entities].each { |key| aggregate[key].select!(&keep) }
@@ -285,6 +422,14 @@ module Hecks
         end
       end
 
+      # Drops transitions whose own command no longer exists, then whatever that
+      # leaves unreachable from the default state; clears `"lifecycle"` outright
+      # once no transition survives.
+      #
+      # @param owner [Hash{String => Object}] an aggregate or entity blueprint entry,
+      #   mutated in place
+      # @param available [Set<String>] every token `tokens` finds still declared
+      # @return [void]
       def prune_lifecycle!(owner, available)
         return unless owner["lifecycle"]
 
@@ -297,9 +442,14 @@ module Hecks
 
       # Every state a path from the default reaches. A transition out of a
       # state nothing reaches can never fire, so a removal that orphans one
-      # goes too: shrinking away `Close` used to leave `Reopen from closed`
-      # behind — qa/stress_domains/generated_revalued_shape was promoted
-      # that way, and bin/model_check reports it as a dead transition.
+      # goes too — without this, shrinking away `Close` leaves `Reopen from
+      # closed` behind, the shape `qa/stress_domains/generated_revalued_shape`
+      # was promoted with, which `bin/model_check` reports as a dead transition.
+      #
+      # @param default [String] the lifecycle's default state name
+      # @param transitions [Array<Hash{String => Object}>] the lifecycle's surviving
+      #   transitions, each with `"from"` (an Array of state names) and `"to"`
+      # @return [Array<String>] every state reachable from `default`, `default` included
       def reachable_states(default, transitions)
         reachable = [default]
         loop do
@@ -310,12 +460,25 @@ module Hecks
         end
       end
 
+      # Drops a command's own unsatisfied references, args, givens and sets.
+      #
+      # @param command [Hash{String => Object}] one command's blueprint entry,
+      #   mutated in place
+      # @param available [Set<String>] every token `tokens` finds still declared
+      # @return [void]
       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
 
+      # Every declaration token `blueprint` currently makes available — what a
+      # `requires` entry elsewhere in the blueprint can point at.
+      #
+      # @param blueprint [Hash{String => Object}] a blueprint as `generate` answers
+      # @return [Set<String>] tokens such as `"aggregate:Ticket"`,
+      #   `"attribute:Ticket.score"`, `"lifecycle:Desk"`, `"reference:Ticket->Desk"`,
+      #   `"command:Ticket.Close"` and `"event:Ticket.TicketOpened"`
       def tokens(blueprint)
         blueprint["aggregates"].each_with_object(Set.new) do |aggregate, set|
           name = aggregate["name"]
@@ -336,6 +499,11 @@ module Hecks
         end
       end
 
+      # Converts a rendered `CamelCase` aggregate/entity name to the `snake_case`
+      # form its own `reference_to`/`sets` field uses.
+      #
+      # @param name [String] a `CamelCase` name
+      # @return [String] `name` in `snake_case`
       def snake(name) = name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
 
       # ── building ────────────────────────────────────────────────────
@@ -343,6 +511,10 @@ module Hecks
       # One seeded pass: the aggregates the forms need, the forms forced
       # onto the first ("primary") aggregate, then extras everywhere.
       class Builder
+        # @param random [Random] the seeded generator every random choice this
+        #   builder makes draws from
+        # @param forms [Array<String>] the `FormCensus::FORMS` names to force onto
+        #   the primary aggregate
         def initialize(random, forms)
           @random = random
           @forms  = forms
@@ -350,6 +522,11 @@ module Hecks
           @policies = []
         end
 
+        # Builds the aggregates the forced forms need, applies each forced form to
+        # the primary aggregate, then sprinkles extras onto every aggregate.
+        #
+        # @return [Hash{String => Object}] `"aggregates"` and `"policies"`, the two
+        #   keys `DomainGenerator.generate` merges `"seed"`/`"forms"` into
         def build
           chain = @forms.intersect?(CHAIN_FORMS)
           count = if chain then 3

data/lib/hecks/fuzzing/era_boundary.rb

@@ -8,7 +8,9 @@ module Hecks
     # target's own real, already-configured `PostgresEra` ledger:
     # does any ancestor era still hold writes nobody has merged forward?
     #
-    # **The bug this targets, named exactly**. Minting a new era (an attribute
+    # ## The bug this targets, named exactly
+    #
+    # Minting a new era (an attribute
     # or aggregate addition — `StorageShape.project`, lib/hecks/ports/
     # persistence/plugins/era/storage_shape.rb) advances the readable head
     # to a new partition; an old checkout, or a process that boots slower
@@ -26,6 +28,8 @@ module Hecks
     # line already answers by hand, run as an ordinary sweep Check instead
     # of only when a human remembers to ask.
     #
+    # ## Connection and safety
+    #
     # The target's real database, read-only, never a disposable one — every
     # other Postgres-touching mode here (`persistence_parity`,
     # `adapter_parity_sqlite`) owns a throwaway schema for the exact
@@ -44,19 +48,27 @@ module Hecks
     module EraBoundary
       module_function
 
+      # Reports whether any ancestor `PostgresEra` era still holds writes the
+      # head has never merged forward, for one target's real database.
+      #
       # `{ checked: true, diverged_total:, breakdown: [{ordinal:, diverged:}] }`
       # or `{ checked: false, kind:, reason: "..." }`. A `true` with
       # `diverged_total.positive?` is the finding this module exists to
       # surface: real post-cut writes an ancestor era is still holding.
       #
-      # `kind:` splits the two things `checked: false` used to mean. Both
-      # answered the same shape, and `bin/qa_sweep` logged that shape as a
-      # held Check either way — so a refused connection or a `Lineage`
-      # defect read, in the ledger, exactly like an audit that ran and
-      # found nothing: counted toward `sweep.made` and the target's clean
+      # `kind:` distinguishes the two different reasons `checked: false` can
+      # occur — without it, `bin/qa_sweep` would log a refused connection
+      # and a `Lineage` defect exactly like an audit that ran and found
+      # nothing, counting either toward `sweep.made` and the target's clean
       # streak. `:not_applicable` is a target with no lineage to audit at
       # all; `:error` is the audit failing to run, which the caller
       # surfaces as a finding rather than holding.
+      #
+      # @param domain_path [String] filesystem path to the target domain's bluebook
+      #   directory, or a directory containing one
+      # @return [Hash{Symbol => Object}] on success, `{checked: true, era_count: Integer,
+      #   breakdown: Array<Hash{ordinal: Integer, diverged: Integer}>, diverged_total: Integer}`;
+      #   otherwise `{checked: false, kind: Symbol, reason: String}`
       def diverged_ancestor_writes(domain_path)
         registry, directory = load_registry(domain_path)
         bluebook = registry.bluebooks.values.first
@@ -92,22 +104,40 @@ module Hecks
         end
       rescue StandardError => e
         # Could not audit is not the same as nothing to audit — a refused
-        # connection, a `Lineage` defect, malformed `.world` settings. Every
-        # one of these used to answer the benign shape and be held.
+        # connection, a `Lineage` defect, malformed `.world` settings. Each
+        # of these answers `:error`, not the benign `:not_applicable` shape,
+        # so `bin/qa_sweep` surfaces it as a finding rather than holding it
+        # as a clean audit.
         failed("#{e.class}: #{e.message}")
       end
 
-      # Nothing to audit — this target holds no PostgresEra lineage, so no
-      # ancestor era can carry post-cut writes. Not a finding, and not
-      # evidence of anything either: the caller logs no Check at all.
+      # Builds the `checked: false` result for a target with no PostgresEra
+      # lineage to audit — no ancestor era can carry post-cut writes when
+      # there is no lineage at all. Not a finding, and not evidence of
+      # anything either: the caller logs no Check at all.
+      #
+      # @param reason [String] human-readable explanation of why no lineage applies
+      # @return [Hash{Symbol => Object}] `{checked: false, kind: :not_applicable, reason: String}`
       def not_applicable(reason) = { checked: false, kind: :not_applicable, reason: reason }
 
-      # The audit itself could not run — reported as a finding, never held.
+      # Builds the `checked: false` result for an audit that could not run
+      # — reported as a finding, never held.
+      #
+      # @param reason [String] human-readable explanation of what failed, typically
+      #   `"#{exception.class}: #{exception.message}"`
+      # @return [Hash{Symbol => Object}] `{checked: false, kind: :error, reason: String}`
       def failed(reason) = { checked: false, kind: :error, reason: reason }
 
-      # The same load `bin/merge_tail` itself performs (that script's own
-      # top half) — a fresh `Registry`, never the ledger's own (this asks
-      # about the swept target's lineage, not QualityControl's own).
+      # Boots a fresh registry for the domain at `domain_path` — the same
+      # load `bin/merge_tail` itself performs (that script's own top half),
+      # never the ledger's own registry (this asks about the swept target's
+      # lineage, not QualityControl's own).
+      #
+      # @param domain_path [String] filesystem path to the target domain's bluebook
+      #   directory, or a directory containing one
+      # @return [Array(Runtime::Registry, String)] the booted registry and the resolved
+      #   bluebook directory path
+      # @raise [Errno::ENOENT] if `domain_path` names no existing domain directory
       def load_registry(domain_path)
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)