hecks 1.4.0 → 1.5.0

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

@@ -8,6 +8,13 @@ module Hecks
       # everything ambiguous left unresolved for a human.
       module Differ
         # Diff two bluebook IRs into the edge's declarations.
+        #
+        # @param held_bluebook [Bluebook::Chapter] the era being translated from
+        # @param current_bluebook [Bluebook::Chapter] the era being translated to
+        # @return [Hash{Symbol => Object}] `:aggregates` (Array<Scaffold::ScaffoldedAggregate>,
+        #   one per matched aggregate carrying a rename or a rule), `:retired` (Array<String>,
+        #   vanished aggregate names with no successor), `:unclaimed` (Array<String>, vanished
+        #   aggregate names left ambiguous)
         def diff(held_bluebook, current_bluebook)
           held_shapes = projections(held_bluebook)
           current_shapes = projections(current_bluebook)
@@ -27,17 +34,31 @@ module Hecks
           { aggregates: aggregates, retired: matched[:retired], unclaimed: matched[:unclaimed] }
         end
 
+        # Projects a bluebook's storage shape and indexes its aggregates by name.
+        #
+        # @param bluebook [Bluebook::Chapter] the bluebook to project
+        # @return [Hash{String => Hash}] the bluebook's storage-shape aggregates (see
+        #   `Runtime::StorageShape.project`), keyed by aggregate name
         def projections(bluebook)
           Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
         end
 
         # A vanished aggregate whose full shape reappears under exactly one
-        # new name was renamed. `retired` is only confident when nothing
+        # new name counts as a rename. `retired` is only confident when nothing
         # remains it could plausibly have become — a vanished aggregate
         # beside an unmatched new one might be a rename-plus-reshape, and
         # writing `retired` there would be a guess that strands data.
         # Anything ambiguous stays unclaimed, and the coverage gate names
         # it until a human decides.
+        #
+        # @param held_shapes [Hash{String => Hash}] the held era's aggregate shapes, keyed by
+        #   name (see `projections`)
+        # @param current_shapes [Hash{String => Hash}] the current era's aggregate shapes,
+        #   keyed by name
+        # @return [Hash{Symbol => Object}] `:pairs` (Hash{String => String, nil}, each current
+        #   name to its matched held name, or nil when unmatched), `:retired` (Array<String>,
+        #   vanished names with no successor), `:unclaimed` (Array<String>, vanished names
+        #   left ambiguous)
         def match_aggregates(held_shapes, current_shapes)
           pairs = {}
           current_shapes.each_key { |name| pairs[name] = held_shapes.key?(name) ? name : nil }
@@ -67,6 +88,13 @@ module Hecks
         # new type name: a retype. Anything else: unresolved, carrying its
         # type-compatible candidates (an empty list is the arrow toward
         # compute, or drop).
+        #
+        # @param held_shape [Hash{String => Object}] the held era's aggregate shape (see
+        #   `projections`)
+        # @param current_shape [Hash{String => Object}] the current era's aggregate shape
+        # @return [Array<Hash{Symbol => Object}>] one rule Hash per changed path — `:kind`
+        #   plus `:from`/`:to` for `:rename`/`:move`/`:retype`, or `:from`/`:candidates` for
+        #   `:unresolved` (see `Renderer#render_rule`); `[]` when nothing changed
         def attribute_rules(held_shape, current_shape)
           rules = []
           rules << identity_hint(held_shape, current_shape)
@@ -93,6 +121,13 @@ module Hecks
 
         # retype pass: same attribute name, same member structure, the
         # type's own name changed
+        #
+        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
+        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
+        #   name
+        # @return [Array<Hash{Symbol => String}>] one `{kind: :retype, from:, to:}` rule per
+        #   attribute whose members are unchanged but whose type name changed; `[]` when none
+        #   match
         def retype_rules(held_attrs, current_attrs)
           (held_attrs.keys & current_attrs.keys).filter_map do |name|
             held = held_attrs[name]
@@ -105,6 +140,16 @@ module Hecks
           end
         end
 
+        # Resolves each vanished path into a rename, move or unresolved rule, appended to
+        # `rules` in place.
+        #
+        # @param rules [Array<Hash{Symbol => Object}>] the rule list to append to; also read
+        #   for `:rename`/`:move` targets an earlier iteration already claimed
+        # @param vanished [Hash{String => Object}] vanished paths to type signature (see
+        #   `vanished_paths`)
+        # @param appeared [Hash{String => Object}] appeared paths to type signature (see
+        #   `appeared_paths`)
+        # @return [void]
         def resolve_vanished_rules!(rules, vanished, appeared)
           vanished.each do |path, signature|
             matches = appeared.select { |_, candidate| candidate == signature }.keys
@@ -125,6 +170,14 @@ module Hecks
         # and members that vanished (or changed type) inside a kept
         # attribute — mirroring exactly what EraGuard will demand coverage
         # for.
+        #
+        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
+        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
+        #   name
+        # @param retyped [Array<String>] type names already claimed by a `:retype` rule,
+        #   excluded here
+        # @return [Hash{String => Object}] each vanished or changed path, dotted for a member,
+        #   valued by that path's type signature
         def vanished_paths(held_attrs, current_attrs, retyped)
           paths = {}
           held_attrs.each do |name, held|
@@ -146,6 +199,17 @@ module Hecks
           paths
         end
 
+        # Current paths that need explaining: whole attributes that appeared, and members
+        # that appeared (or changed type) inside a kept attribute — the mirror of
+        # `vanished_paths`.
+        #
+        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
+        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
+        #   name
+        # @param retyped [Array<String>] type names already claimed by a `:retype` rule,
+        #   excluded here
+        # @return [Hash{String => Object}] each appeared or changed path, dotted for a
+        #   member, valued by that path's type signature
         def appeared_paths(held_attrs, current_attrs, retyped)
           paths = {}
           current_attrs.each do |name, current|
@@ -173,24 +237,51 @@ module Hecks
         # `check_identity_unchanged!` is the real gate this only hints
         # toward, the same "tool proactively guides you" pattern the
         # generic unresolved message already gives unfed fields.
+        #
+        # @param held_shape [Hash{String => Object}] the held era's aggregate shape
+        # @param current_shape [Hash{String => Object}] the current era's aggregate shape
+        # @return [Hash{Symbol => Object}, nil] `{kind: :unresolved, from: :identity,
+        #   candidates: []}` when the identity paths differ; nil when they match
         def identity_hint(held_shape, current_shape)
           return if held_shape["identity"] == current_shape["identity"]
 
           { kind: :unresolved, from: :identity, candidates: [] }
         end
 
+        # Finds appeared paths type-compatible with a vanished path's own signature.
+        #
+        # @param appeared [Hash{String => Object}] appeared paths to type signature (see
+        #   `appeared_paths`)
+        # @param signature [Object] the vanished path's own type signature to match against
+        # @return [Array<String>] appeared paths whose scalar signature (see `scalar_of`)
+        #   matches `signature`'s
         def compatible_candidates(appeared, signature)
           appeared.select { |_, candidate| scalar_of(candidate) == scalar_of(signature) }.keys
         end
 
+        # Reduces a type signature to the shape `compatible_candidates` compares by.
+        #
+        # @param signature [Object, Hash] a path's type signature
+        # @return [Object] `signature["members"]` for a container Hash, else `signature`
+        #   unchanged
         def scalar_of(signature) = signature.is_a?(Hash) ? signature["members"] : signature
 
+        # Reads a container attribute's own members, keyed by name.
+        #
+        # @param attribute [Hash{String => Object}] one path's type signature
+        # @return [Hash{String => Object}] each member's name to its type; `{}` when
+        #   `attribute` is not a container
         def members_of(attribute)
           return {} unless container?(attribute)
 
           attribute["type"]["members"].to_h { |member| [member["name"], member["type"]] }
         end
 
+        # Reports whether a type signature is a container (value object or entity), not a
+        # scalar.
+        #
+        # @param attribute [Hash{String => Object}] one path's type signature
+        # @return [Boolean] true if `attribute["type"]` is a Hash, false for a scalar
         def container?(attribute) = attribute["type"].is_a?(Hash)
       end
     end

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

@@ -5,6 +5,10 @@ module Hecks
       # ambiguities as parse-refusing `unresolved` constructs, never
       # comments, so an unresolved file can only boot into a refusal.
       module Renderer
+        # Renders a scaffolded edge as loadable `.bluebook` translation source.
+        #
+        # @param edge [Scaffold::Edge] the edge to render
+        # @return [String] the edge's `.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|
@@ -19,6 +23,12 @@ module Hecks
           "#{lines.join("\n")}\n"
         end
 
+        # Renders one scaffolded rule as a line of `.bluebook` source.
+        #
+        # @param rule [Hash{Symbol => Object}] a rule Hash as `Differ#attribute_rules` builds
+        #   it: `:kind` plus `:from`/`:to`, or `:from`/`:candidates` for `:unresolved`
+        # @return [String, nil] the rendered line; nil if `rule[:kind]` is none of `:rename`,
+        #   `:move`, `:retype` or `:unresolved`
         def render_rule(rule)
           case rule[:kind]
           when :rename then "rename :#{rule[:from]}, to: :#{rule[:to]}"
@@ -30,6 +40,11 @@ module Hecks
           end
         end
 
+        # Renders a path as bluebook source: a Symbol literal when bare, a String literal
+        # when dotted.
+        #
+        # @param path [String, Symbol] a bare or dotted path
+        # @return [String] `":name"` for a bare path, `path.inspect` for a dotted one
         def render_path(path) = path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
       end
     end

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

@@ -6,10 +6,18 @@ module Hecks
       # Put the rendered edge on disk, regenerating in place when a file
       # for the same shape pair already exists.
       module Writer
+        # Renders an edge and writes it under `directory/translations`, regenerating in
+        # place when a file for the same shape pair already exists.
+        #
         # The edge file, regenerated in place when one for the same shape
         # pair already exists (matched textually — an unresolved file
         # cannot be loaded to ask, that being the whole point of
         # unresolved).
+        #
+        # @param directory [String] the domain's root directory
+        # @param edge [Scaffold::Edge] the edge to render and write
+        # @return [String] the path written, either the matched existing file or a new
+        #   `<ordinal>-<label>.bluebook`
         def write!(directory, edge)
           translations_dir = File.join(directory, "translations")
           FileUtils.mkdir_p(translations_dir)

data/lib/hecks/ports/query/in_memory.rb

@@ -18,6 +18,19 @@ module Hecks
 
         module_function
 
+        # Filters, orders and pages `records` against a declared query specification.
+        #
+        # @param records [Array<Runtime::Instance, Hash>] the candidate records to filter —
+        #   an Instance, a Value, or a plain row hash per record (see `FieldPath.dig`)
+        # @param declared [QuerySpecification::Common::Options,
+        #   Bluebook::Behaviour::ReadModel::FilteredOptions] the specification providing
+        #   `wheres`, `order_by`, `offset` and `limit`
+        # @param args [Hash{Symbol => Object}] bound values for any Symbol placeholder in a
+        #   where clause, `offset`, or `limit`
+        # @param registry [Runtime::Registry, nil] the booted registry, passed through to a
+        #   registry-aware comparison; nil when none is available
+        # @return [Array<Runtime::Instance, Hash>] the matching records, ordered and paged;
+        #   the same element type as `records`
         def execute(records, declared, args = {}, registry: nil)
           matched = records.select do |record|
             declared.wheres.all? do |clause|
@@ -47,18 +60,38 @@ module Hecks
         end
 
         # The comparator table itself lives in
-        # QuerySpecification::Common::Comparison — this module and
-        # Runtime::QueryInterpreter used to carry a copy each, and the two
-        # drifted (see that file's own comment for what it cost). What
-        # stays here is how a value is reached for this path: a registry
-        # arrives as an argument rather than as instance state, and the
-        # field is dug through FieldPath before it arrives.
+        # QuerySpecification::Common::Comparison, not duplicated per
+        # caller — this module and Runtime::QueryInterpreter drifted
+        # when each carried its own copy (see that file's own comment
+        # for what it cost). What stays here is how a value is reached
+        # for this path: a registry arrives as an argument rather than
+        # as instance state, and the field is dug through FieldPath
+        # before it arrives.
+        # @param clause [QuerySpecification::Common::WhereClause] the declared comparison
+        # @param held [Object, nil] the record's own value for `clause.field`
+        # @param args [Hash{Symbol => Object}] bound values for a Symbol-named `clause.value`
+        # @param registry [Runtime::Registry, nil] used only by `none_in_state`; see
+        #   `Comparison.holds?`
+        # @return [Boolean] whether the comparison holds
+        # @raise [Runtime::WiringError] if `clause.op` names no comparator in
+        #   `Comparison`'s table, or `none_in_state`'s target aggregate has no wired repository
         def holds?(clause, held, args, registry: nil)
           Comparison.holds?(clause.op, held, comparable(resolve(clause.value, args)), registry: registry)
         end
 
+        # Resolves a where-clause value, looking up a Symbol placeholder in `args`.
+        #
+        # @param value [Object] a literal value, or a Symbol naming a key in `args`
+        # @param args [Hash{Symbol => Object}] bound argument values
+        # @return [Object] `args[value]` when `value` is a Symbol, else `value` unchanged
         def resolve(value, args) = value.is_a?(Symbol) ? args[value] : value
 
+        # Normalises a value into the shape `Comparison` compares against.
+        #
+        # @param value [Runtime::Value, Hash, Object, nil] a held or wanted value; a
+        #   `Runtime::Value` is read through its `to_h`
+        # @return [Object, nil] the sole numeric member, or the sole member, of a Hash-shaped
+        #   value; otherwise `value` unchanged
         def comparable(value) = Comparison.comparable(value)
       end
     end

data/lib/hecks/ports/query/ordering.rb

@@ -24,6 +24,21 @@ module Hecks
       module Ordering
         module_function
 
+        # Orders an Array of rows by the declared order, with identity as the total-order
+        # tiebreaker.
+        #
+        # @param rows [Array<Object>] the rows to order; any shape `identity` and the block
+        #   can read (a `Runtime::Instance`, a plain Hash row, …)
+        # @param order_by [QuerySpecification::Common::OrderBy, nil] the declared order;
+        #   nil orders by identity alone
+        # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] where a
+        #   nil-valued row sorts, passed to `NullPolicy.order`; nil uses its native default
+        # @param identity [Proc] yields a row, returns its comparable identity value, used
+        #   as the stable tiebreaker
+        # @yieldparam row [Object] one row being ordered
+        # @yieldreturn [Object, nil] the row's comparable value for `order_by`'s field
+        # @return [Array<Object>] `rows`, ordered by `order_by` then identity (identity
+        #   alone when `order_by` is nil)
         def apply(rows, order_by, null_semantics = nil, identity:, &value_of)
           # Stable, because sort_by is not : two rows whose identity ties would
           # otherwise swap arbitrarily, and a tier meant to remove store-dependence

data/lib/hecks/ports.rb

@@ -20,6 +20,7 @@ require_relative "ports/query"
 require_relative "ports/projection"
 require_relative "ports/extraction"
 require_relative "ports/identity_generation"
+require_relative "ports/key_vault"
 require_relative "ports/authorization"
 require_relative "ports/identity_resolution"
 require_relative "ports/authentication"

data/lib/hecks/projections/bootstrap_table.rb

@@ -9,14 +9,16 @@ module Hecks
     #
     # While `MetaValidator.bootstrapping?` the grammar table does not exist
     # yet, so `WordGate#method_missing` and `RuleReference#lookup` cannot
-    # read `calls:`/`resolves_via:`/`disambiguator:` off it. They used to
-    # read two hand-kept Hashes instead, each "kept in sync by hand" with
-    # those columns. Kept in sync by hand meant a subset: 48 of the 87 live
-    # `calls:` rows, chosen word by word by grepping which ones the core
-    # chapters happened to use during bootstrap. A partition, not a filter:
-    # every live row now lands in the table, and the ones no bootstrap
-    # chapter calls cost nothing — a builder with its own `def` never
-    # reaches `method_missing` at all.
+    # read `calls:`/`resolves_via:`/`disambiguator:` off it — this table is
+    # what they read instead.
+    #
+    # A partition, not a filter: every live row lands in the table, not only
+    # the ones a bootstrap chapter happens to call. Picking a subset by
+    # grepping which words the core chapters use during bootstrap would risk
+    # quietly dropping any word a chapter starts using later. Including
+    # every row instead costs nothing: a builder with its own `def` never
+    # reaches `method_missing` at all, so a row no bootstrap chapter calls
+    # is simply never read.
     #
     # The table cannot be built at boot for the same reason it exists: it
     # is read before the grammar it comes from has been assembled. So it is
@@ -43,11 +45,24 @@ module Hecks
 
       module_function
 
+      # Projects the bootstrap fallback table — the only real work this projector
+      # does, `bluebook` unused because the table is the whole language's grammar,
+      # not any one chapter's.
+      #
+      # @param bluebook [Bluebook::Chapter] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
+      #   `Projector::Target` calling convention
+      # @return [String] the rendered `lib/hecks/bluebook/dsl/bootstrap_table.rb` source
       def call(bluebook:, options: {}) = render(bluebook)
 
       # Retired rows are out of the language; admitted and deprecated rows
       # still dispatch — the same `status != "retired"` reading
       # `GenericDispatch.shape_for` gives the live table.
+      #
+      # @return [Array<Hash{Symbol => String}>] every non-retired keyword row, each with
+      #   at least `:context`, `:word`, `:status`, `:calls`, `:resolves_via` and
+      #   `:disambiguator`, values stringified
       def live_keywords
         Bluebook::MetaValidator::SyntaxBoot.call[:keywords].reject { |row| row[:status] == "retired" }
       end
@@ -57,6 +72,13 @@ module Hecks
       # An overloaded word has one row per argument shape, and they all
       # name the same method. Two that don't would make the table keep
       # whichever came last, so that is refused instead.
+      #
+      # @param rows [Array<Hash{Symbol => String}>] the keyword rows to build from,
+      #   defaulting to every live one
+      # @return [Hash{Array(String, String) => Symbol}] each `calls:`-declaring row's
+      #   `[context, word]` mapped to the method name it dispatches to
+      # @raise [Projections::BootstrapTable::Conflict] if two rows sharing a
+      #   `[context, word]` name different methods
       def calls(rows = live_keywords)
         rows.reject { |row| row[:calls].to_s.empty? }
             .group_by { |row| [row[:context], row[:word]] }
@@ -71,6 +93,12 @@ module Hecks
       # `[word, context] => { resolves_via:, disambiguator: }` —
       # RuleReference's own key order, blank columns omitted, the same
       # shape its live `lookup` answers.
+      #
+      # @param rows [Array<Hash{Symbol => String}>] the keyword rows to build from,
+      #   defaulting to every live one
+      # @return [Hash{Array(String, String) => Hash{Symbol => String}}] each
+      #   `resolves_via:`-declaring row's `[word, context]` mapped to its rule Hash,
+      #   with any blank `resolves_via`/`disambiguator` column omitted
       def resolves(rows = live_keywords)
         rows.reject { |row| row[:resolves_via].to_s.empty? }.to_h do |row|
           rule = { resolves_via: row[:resolves_via], disambiguator: row[:disambiguator] }
@@ -78,6 +106,13 @@ module Hecks
         end
       end
 
+      # Renders the bootstrap table as committable Ruby source — `CALLS` and
+      # `RESOLVES` frozen Hash literals under the generated-file header.
+      #
+      # @param _bluebook [Bluebook::Chapter] ignored; the table draws from the whole
+      #   language's grammar, not this argument
+      # @return [String] the full `lib/hecks/bluebook/dsl/bootstrap_table.rb` source,
+      #   ready to write to disk
       def render(_bluebook)
         rows = live_keywords
         calls_lines = calls(rows).map { |key, target| "          #{key.inspect} => #{target.inspect}" }