hecks 2.8.0 → 2.9.0

data/lib/hecks/query_specification/common/null_policy.rb

@@ -1,37 +1,23 @@
 module Hecks
   module QuerySpecification
     module Common
-      # Null-handling shared between the in-memory and SQL query
-      # engines: stable null-aware ordering (#order, #sql_order) and
-      # which comparators a null value can never satisfy (#unmatchable?,
-      # #sql_predicate) — kept in one place because Memory, Postgres and
-      # SQLite each default nulls differently and must be made to agree
-      # explicitly rather than leaking their own native behavior.
+      # Null handling shared by the in-memory and SQL query engines: null-aware ordering
+      # and the comparators a null can never satisfy, so every adapter agrees.
       module NullPolicy
         module_function
 
         # Sorts records in memory by one key, placing the null-keyed ones where
         # the policy says and keeping ties in their incoming order.
         #
-        # Stable on purpose : rows arrive already in identity order from
-        # `Ports::Query::Ordering`, and that base is what makes a tie deterministic
-        # rather than store-dependent. A plain sort_by is not stable in Ruby, so
-        # equal keys would shuffle and the identity tier would be lost exactly
-        # where it is needed. Descending reverses both partitions, so a tie reads
-        # identity-descending too — the same total order sql_order renders as
-        # `field DESC, id DESC`.
+        # Stable on purpose: rows arrive in identity order, which makes ties deterministic.
+        # Descending reverses both partitions, matching `sql_order`'s `field DESC, id DESC`.
         #
         # @param records [Array<Object>] the rows to order, already in identity order
-        # @param direction [Symbol, String] `desc` in any letter case sorts descending;
-        #   anything else ascending
-        # @param policy [NullSemantics, nil] where nulls go: mode `first` or `last`; `nil` or
-        #   any other mode (`native`) puts nulls first ascending and last descending
-        # @yield reads the sort key out of one record
+        # @param direction [Symbol, String] `desc` sorts descending; anything else ascending
+        # @param policy [NullSemantics, nil] mode `first` or `last`; otherwise `native`
         # @yieldparam record [Object] one element of `records`
-        # @yieldreturn [Comparable, nil] the key, mutually comparable across records; `nil`
-        #   marks the record as null-keyed
-        # @return [Array<Object>] a new Array holding every record in the requested order
-        # @raise [ArgumentError] if two non-nil keys cannot be compared with each other
+        # @yieldreturn [Comparable, nil] the sort key; `nil` marks the record null-keyed
+        # @return [Array<Object>] a new Array in the requested order
         def order(records, direction:, policy: nil, &key)
           descending = direction.to_s.downcase == "desc"
           null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
@@ -50,27 +36,13 @@ module Hecks
         # Renders the `ORDER BY` terms for one expression, with an explicit
         # `NULLS FIRST`/`NULLS LAST` and an `id` tiebreak in the same direction.
         #
-        # M3 — an undeclared (`native`) null policy still renders a
-        # `NULLS ...` clause. Rendering none leaves each dialect's own
-        # default to decide: Postgres puts nulls last on ASC (and first
-        # on DESC), while `#order` above — this same "native" default,
-        # for Memory — puts nulls first on ASC (and last on DESC), the
-        # SQLite convention. Same query, same data, different row order
-        # depending only on which adapter ran it. Rendered explicitly
-        # here instead, so an undeclared policy means the same total
-        # order everywhere rather than "whatever this store already does"
-        # — matching `#order`'s own default rather than the other way
-        # round, since that default is unconditional (Memory/Heki have no
-        # dialect to defer to) and SQLite already agrees with it natively.
+        # An undeclared (`native`) policy still renders `NULLS ...`, because dialects
+        # differ (Postgres puts nulls last on ASC); this matches `#order`'s default.
         #
-        # @param expression [String] the SQL expression to order by, already quoted or
-        #   built by the adapter; interpolated as is
-        # @param direction [Symbol, String] `desc` in any letter case renders `DESC`;
-        #   anything else `ASC`
-        # @param policy [NullSemantics, nil] mode `first` or `last` pins the nulls; `nil` or
-        #   any other mode renders `NULLS FIRST` ascending and `NULLS LAST` descending
-        # @return [String] the terms without the `ORDER BY` keyword, such as
-        #   `"price ASC NULLS FIRST, id ASC"`
+        # @param expression [String] the SQL expression, interpolated as is
+        # @param direction [Symbol, String] `desc` renders `DESC`; anything else `ASC`
+        # @param policy [NullSemantics, nil] mode `first` or `last` pins the nulls
+        # @return [String] the terms without `ORDER BY`, such as `"price ASC NULLS FIRST, id ASC"`
         def sql_order(expression, direction, policy)
           direction = direction.to_s.downcase == "desc" ? "DESC" : "ASC"
           nulls = case policy&.mode.to_s
@@ -81,34 +53,13 @@ module Hecks
           "#{expression} #{direction}#{nulls}, id #{direction}"
         end
 
-        # **The comparators a NULL cannot satisfy** — the other half of
-        # `sql_predicate` below. That one answers "the value compared to is
-        # null" (`eq: nil` -> IS NULL, `ne: nil` -> IS NOT NULL, a real
-        # convention both adapters already shared). This one answers the
-        # case nothing covered: the row's own value is null and the value
-        # compared to is not.
+        # Comparators a NULL row value can never satisfy.
         #
-        # SQL says unknown. `NULL <> 'red'` is NULL, not true, so the row
-        # is not returned. Ruby says `nil != "red"` is true, so it is. The
-        # two adapters therefore answered the same query on the same data
-        # differently — Memory returning a row SQLite omitted — which is
-        # not a difference of opinion a caller can plan around.
-        #
-        # Resolved toward SQL, and not because SQL is the store: an absent
-        # or null field is unknown, not a value, and a comparison against
-        # unknown is unknown rather than true. Making SQL match Ruby
-        # instead would mean compiling every `ne:` to
-        # `(col <> $1 OR col IS NULL)` — more to get right in two
-        # dialects, and a reliable way to lose an index — to make a real
-        # query engine agree with an in-memory one.
-        #
-        # `none_in_state` is deliberately not here: it is a 9th, vendored
-        # comparator whose `held` is a reference id, and a row holding no
-        # reference is genuinely "not in that state" rather than unknown.
+        # SQL treats `NULL <> 'red'` as unknown, so the row is dropped; Memory follows SQL.
+        # `none_in_state` is excluded: a row with no reference is not in that state.
         NULL_UNMATCHABLE = %w[eq ne lt lte gt gte in contains].freeze
 
-        # Decides whether a comparison is lost before it starts because the row's
-        # own value is null — the rule `NULL_UNMATCHABLE`'s comment argues for.
+        # Decides whether a comparison is lost because the row's own value is null.
         #
         # @param operation [Symbol, String] the comparator name, such as `:ne`
         # @param held [Object, nil] the row's own value for the field
@@ -119,9 +70,8 @@ module Hecks
           held.nil? && !want.nil? && NULL_UNMATCHABLE.include?(operation.to_s)
         end
 
-        # Renders the SQL for a comparison against a null value — `eq: nil` as
-        # `IS NULL`, `ne: nil` as `IS NOT NULL` — so an adapter never binds a
-        # `NULL` parameter to `=` or `<>`.
+        # Renders the SQL for a comparison against a null value (`IS NULL`/`IS NOT NULL`),
+        # so an adapter never binds a `NULL` parameter to `=` or `<>`.
         #
         # @param expression [String] the SQL expression for the field, interpolated as is
         # @param operation [Symbol, String] the comparator name

data/lib/hecks/query_specification/common/options.rb

@@ -3,12 +3,8 @@ require_relative "null_semantics"
 module Hecks
   module QuerySpecification
     module Common
-      # The attribute set every query-shaped construct shares — wheres,
-      # ordering, paging, cursor, authorization, null semantics,
-      # inspection mode — plus `options_to_h`/`extra_options_to_h` for
-      # serializing it. Both Bluebook::Query and
-      # QuerySpecification::ReadModel::Specification subclass this
-      # rather than each declaring the same fields twice.
+      # The attribute set every query-shaped construct shares, plus `options_to_h` and
+      # `extra_options_to_h` for serializing it.
       class Options
         attr_reader :wheres, :order_by, :limit, :offset, :cursor,
                     :authorization, :null_semantics, :inspection

data/lib/hecks/query_specification/common/where_clause.rb

@@ -1,16 +1,8 @@
 module Hecks
   module QuerySpecification
     module Common
-      # `target` — which many-side `include`d aggregate this clause applies
-      # to on a `read_model` with more than one (ADR 0055's own `on:`,
-      # `ReadModelBuilder#where_impl`). Always `nil` for a plain `Query`'s
-      # own `where` (that builder never overrides `where_impl` to accept
-      # `on:`), and `nil` for a `read_model` with a single many-side head,
-      # where naming one is unnecessary. `to_h` omits the key entirely
-      # rather than emitting `target: nil` — the same "absent, not null"
-      # convention `count`/`median_field` already established
-      # (`lib/hecks/bluebook/read_model.rb`), so every read model that
-      # never uses `on:` keeps its existing wire shape byte-identical.
+      # One filter clause. `target` names the many-side `include`d aggregate on a
+      # `read_model` with several (ADR 0055); `to_h` omits it when `nil`.
       WhereClause = Struct.new(:field, :op, :value, :target, keyword_init: true) do
         def to_h
           base = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }

data/lib/hecks/query_specification/field_path.rb

@@ -1,44 +1,20 @@
 module Hecks
   module QuerySpecification
-    # One reading of a dotted query-field path, shared by every place that
-    # would otherwise invent its own. Left to themselves they disagree: a
-    # reference interpreter doing a bare `record[field]` lookup silently
-    # matches nothing for a dotted path, an SQL side that splits dots but
-    # judges numericness from the first nested segment only quietly
-    # compares a two-level path as text, and a build seal walks the
-    # declaration graph a third way. Three implementations of "what does
-    # pizza.price_cents.cents mean" is two more than a language gets to
-    # have.
+    # One reading of a dotted query-field path, shared by every caller that walks one.
     #
-    # Two sides, deliberately in one file so they cannot drift:
-    #
-    #   dig(holder, field)        — value side: walk a record's held state,
-    #                               segment by segment, through Value
-    #                               objects and plain hashes alike.
-    #   leaf_attribute / numeric? — declaration side: walk the declared
-    #                               shape to the attribute a path lands on.
-    #                               Callers supply value-object lookup as a
-    #                               block, because an Aggregate and a
-    #                               mid-build AggregateBuilder hold their
-    #                               shapes differently but walk the same.
+    # `dig` walks a record's held state; `leaf_attribute`/`numeric?` walk the declared shape.
     module FieldPath
       module_function
 
       NUMERIC_PRIMITIVES = %w[Integer Float].freeze
+      INTEGER_PRIMITIVES = %w[Integer].freeze
+      BOOLEAN_PRIMITIVES = %w[TrueClass FalseClass].freeze
       SCALAR_PRIMITIVES  = %w[String Integer Float TrueClass FalseClass].freeze
 
       # Reads the value a dotted field path names out of a record's held state.
       #
-      # The held value a dotted field names, or nil — never a raise. The
-      # first segment reads off the record (an Instance, a Value, or a
-      # plain row hash); the rest read through whatever each step holds. A
-      # stored nested value object is a plain hash by the time it is read
-      # back, keyed by symbol in memory and by string off a wire decode,
-      # so both spellings are tried — `key?` first, never `||`, because
-      # `||` falls through a genuinely-stored `false` to the other
-      # spelling (usually absent) and returns `nil` instead. The seal
-      # admits boolean leaves (`SCALAR_PRIMITIVES` below), so a `false`
-      # here is a real, held answer, not a missing one.
+      # Nested value objects come back as hashes keyed by symbol (memory) or string (wire),
+      # so both are tried, `key?` first: `||` would turn a stored `false` into `nil`.
       #
       # @param holder [Runtime::Instance, Runtime::Value, Hash, nil] the record, value
       #   object or row Hash the first segment is read from
@@ -52,8 +28,7 @@ module Hecks
         field.to_s.split(".").reduce(holder) { |current, segment| read(current, segment) }
       end
 
-      # Reads one path segment off whatever the previous step held — a single
-      # step of `dig`.
+      # Reads one path segment off whatever the previous step held.
       #
       # @param current [Runtime::Instance, Runtime::Value, Hash, Array, nil] the value the
       #   walk has reached; a Hash is tried by Symbol key, then by String key
@@ -68,14 +43,8 @@ module Hecks
           return current.key?(sym) ? current[sym] : current[segment]
         end
 
-        # M5 — "or nil, never raise" is this method's whole contract, and
-        # an Array broke it: `Array#[]` demands an Integer index, so
-        # `current[segment]` (a String) raised `TypeError` straight
-        # through `dig` instead of answering nil. A dotted path stepping
-        # into a list_of attribute (`where "tags.name" == "x"` against a
-        # bare list, rather than each element) has no single member a
-        # bare index would name anyway — nil is the honest answer, the
-        # same one a dangling reference or a missing key already gets.
+        # A list has no single member a String index could name; `Array#[]` would raise
+        # TypeError, breaking dig's "nil, never raise" contract.
         return nil if current.is_a?(Array)
 
         current[segment]
@@ -83,21 +52,16 @@ module Hecks
 
       # Walks the declared shape to the attribute a dotted path lands on.
       #
-      # The declared attribute a path lands on, or nil. `segments` is the
-      # dotted tail — for a bare field it is empty and the root attribute
-      # is its own leaf. The walk stops dead at a reference (an id is a
-      # scalar; nothing nests under it) and at any member the declared
-      # value object does not carry.
+      # `segments` is the dotted tail, empty for a bare field. The walk stops at a reference
+      # and at any member the declared value object does not carry.
       #
-      # @param attribute [Bluebook::Attribute, nil] the root attribute the path's first
-      #   segment names; `nil` (no such attribute) answers `nil`
+      # @param attribute [Bluebook::Attribute, nil] the root attribute; `nil` answers `nil`
       # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
       # @yield looks a value object up by name in the caller's own declarations
-      # @yieldparam type [String] the type name of the attribute being stepped into
-      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil` when
-      #   the type is not a value object the caller knows
-      # @return [Bluebook::Attribute, nil] the attribute at the end of the path; `nil` when
-      #   a step crosses a reference, an undeclared type or a member that does not exist
+      # @yieldparam type [String] the type name being stepped into
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
+      # @return [Bluebook::Attribute, nil] the leaf; `nil` when a step crosses a reference or
+      #   lands on an undeclared type or missing member
       def leaf_attribute(attribute, segments)
         current = attribute
         segments.each do |segment|
@@ -109,43 +73,39 @@ module Hecks
         current
       end
 
-      # Decides from the declared shape whether a field path holds a number.
+      # Whether a field path lands on one of `primitives`: itself, or (bare field only) a
+      # value object with a member typed as one.
       #
-      # May an ordered comparator (lt/lte/gt/gte) land here, and may an
-      # `ORDER BY` cast here numerically? A bare field keeps the one-level
-      # convention every adapter already implements: a numeric primitive,
-      # or a value object carrying at least one numeric member. A dotted
-      # path must land on a numeric primitive itself — the convention does
-      # not reach through a named path, it is the absence of one.
-      #
-      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
-      #   `nil` answers `false`
+      # @param attribute [Bluebook::Attribute, nil] the root attribute; `nil` answers `false`
       # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @param primitives [Array<String>] the primitive type names that count as a match
       # @yield looks a value object up by name, as for `leaf_attribute`
-      # @yieldparam type [String] the type name to look up
-      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
-      # @return [Boolean] `true` when the leaf is an `Integer` or `Float`, or a bare field
-      #   naming a value object with at least one such member; `false` for a list, a
-      #   reference, or a path that lands nowhere
-      def numeric?(attribute, segments, &)
+      # @return [Boolean] `false` for a list, a reference, or a path that lands nowhere
+      def matches_primitive?(attribute, segments, primitives, &)
         leaf = leaf_attribute(attribute, segments, &)
         return false if leaf.nil? || leaf.list? || leaf.reference?
-        return true if NUMERIC_PRIMITIVES.include?(leaf.type.to_s)
+        return true if primitives.include?(leaf.type.to_s)
         return false unless segments.empty?
 
         shape = yield(leaf.type.to_s)
-        !shape.nil? && shape.attributes.any? { |member| NUMERIC_PRIMITIVES.include?(member.type.to_s) }
+        !shape.nil? && shape.attributes.any? { |member| primitives.include?(member.type.to_s) }
       end
 
-      # Decides whether a path ends on a scalar primitive that every engine
-      # compares the same way.
+      # @return [Boolean] whether a field path holds a number (`Integer` or `Float`)
+      def numeric?(attribute, segments, &) = matches_primitive?(attribute, segments, NUMERIC_PRIMITIVES, &)
+
+      # @return [Boolean] whether a field path holds specifically an `Integer` (not `Float`)
+      def integer?(attribute, segments, &) = matches_primitive?(attribute, segments, INTEGER_PRIMITIVES, &)
+
+      # @return [Boolean] whether a field path holds a `TrueClass`/`FalseClass`
+      def boolean?(attribute, segments, &) = matches_primitive?(attribute, segments, BOOLEAN_PRIMITIVES, &)
+
+      # Decides whether a path ends on a scalar primitive every engine compares alike.
       #
-      # A dotted path must end on a scalar member — landing on a value
-      # object would hand SQL a JSON object where the reference
-      # interpreter unwraps a hash, and the two would answer differently.
+      # A dotted path landing on a value object would give SQL a JSON object where the
+      # reference interpreter unwraps a hash, so the two would disagree.
       #
-      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
-      #   `nil` answers `false`
+      # @param attribute [Bluebook::Attribute, nil] the root attribute; `nil` answers `false`
       # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
       # @yield looks a value object up by name, as for `leaf_attribute`
       # @yieldparam type [String] the type name to look up

data/lib/hecks/query_specification/hop_path.rb

@@ -2,61 +2,26 @@ require_relative "../naming"
 
 module Hecks
   module QuerySpecification
-    # One reading of a dotted query-field path that hops through a
-    # reference into another aggregate's own shape — FieldPath's
-    # sibling, not its member. FieldPath walks a shape, which cannot
-    # loop, and answers nil, never raising, because there is nothing
-    # left to say beyond "not found." HopPath walks the reference
-    # graph instead — `BluebookBuilder#validate_no_bidirectional_references!`
-    # refuses any reference cycle at declaration time (ADR 0025,
-    # "References" — widened from a direct pair to any ring, DFS over
-    # the chapter's own reference graph), so what's left to guard here
-    # is depth, not cycles: MAX_HOPS below, and this module's own
-    # `refusal` states for a target the chapter doesn't resolve. A walk
-    # here still needs to say why it stopped, not just that it did.
+    # One reading of a dotted query-field path that hops through a reference with `/`.
     #
-    # Every method below takes an attribute array, never a "shape"
-    # object — deliberately, because the two real callers hold their
-    # attributes differently. `AggregateBuilder` (tier-1 seal, mid-
-    # build) exposes `attributes` as a plain reader, but its own
-    # `attribute(name, type = String, ...)` is the DSL's attribute-
-    # declaring method — calling it as a finder would silently mint a
-    # new String attribute instead of looking one up. A sealed
-    # `Aggregate` (tier-2 seal, and every runtime target) has a
-    # real `attribute(name)` finder, but taking the array either way
-    # sidesteps the mismatch instead of asking every caller to know
-    # which kind of object it holds.
+    # Takes attribute arrays, not shapes: AggregateBuilder's `attribute(name)` declares rather
+    # than finds, so the two real callers cannot share a finder.
     module HopPath
       module_function
 
       Hop = Struct.new(:attribute, :target_name, :target, keyword_init: true)
 
-      # refusal: nil (clean), :unresolvable (a hop's target cannot be
-      # found — cross-domain, or simply not declared in this chapter),
-      # :too_deep (see MAX_HOPS below).
+      # `refusal` is nil when clean, `:unresolvable` when a hop's target is not found,
+      # `:too_deep` when the chain exceeds MAX_HOPS.
       Plan = Struct.new(:hops, :tail, :refusal, keyword_init: true)
 
-      # A hop chain long enough to matter is long enough to be a
-      # mistake — not a guard against a walk that cannot terminate.
-      # Nothing here loops forever regardless of how the reference
-      # graph is shaped: a hop chain is a literal dotted string, fixed
-      # at declaration time, and every step consumes exactly one of
-      # its own segments — the walk is bounded by what was typed, not
-      # by the graph. A self-referential aggregate hopping through
-      # itself more than once (`"parent.parent.name"`, a grandparent
-      # query) is real, common, and perfectly safe; this exists only
-      # to refuse a chain nobody meant to write this long.
+      # Bounds hop chains: a longer one is a mistake, not a runaway walk, since each
+      # step consumes one segment of the typed path.
       MAX_HOPS = 8
 
       # Names the path segment a reference attribute answers to.
       #
-      # The segment name a Reference answers to in a hop path — its own
-      # declared attribute name, unchanged (ADR 0025, "References":
-      # `reference_to` mints that bare name, no `_id`, so there is
-      # no derivation left to apply). `proposal/client` (a query hop)
-      # and `proposal.client` (the Ruby accessor,
-      # `Facade::Handle#define_reference_accessors`) name the same
-      # concept the same way.
+      # The attribute's own declared name, unchanged (ADR 0025).
       #
       # @param attribute [Bluebook::Attribute] a reference-typed attribute
       # @return [String] the attribute's declared name
@@ -65,17 +30,8 @@ module Hecks
       # Decides whether a field path starts by hopping through one of the given
       # references, without resolving the reference's target.
       #
-      # Does this path's head cross into another record via `/`? The
-      # operator is the answer now, not a name collision to arbitrate —
-      # `.` walks fields inside this record, `/` crosses into another
-      # one, so a path with no `/` is never a hop, full stop, and the
-      # old "a real local attribute wins first" rule (needed only
-      # because `.` was overloaded for both meanings, and `client_id`
-      # vs `client` was how the two were told apart) has nothing left
-      # to arbitrate. Answerable from `attributes` alone — a Reference
-      # knows its own `target_name` at declaration, before it can
-      # `resolve` it — which is what lets the aggregate seal recognise
-      # a hop it cannot yet check.
+      # A path with no `/` is never a hop: `.` walks fields inside a record, `/` crosses
+      # into another one.
       #
       # @param field [String, Symbol] the query field path, such as `:"client/status"`
       # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
@@ -91,17 +47,6 @@ module Hecks
 
       # Resolves the first hop of a field path and hands back what is left to walk.
       #
-      # **One step**: does `field`'s head hop through one of `attributes`'
-      # own references? Answers the resolved `Hop` plus the string
-      # still left to walk (itself possibly another `/`-hop, against
-      # the target's own attributes, or a plain `.`-dotted field walk
-      # once the hops run out) — or nil, when the head names nothing or
-      # the path has no `/` at all. This is the one primitive
-      # Runtime::ReferenceHop needs: it recurses hop by hop through its
-      # own `apply`, one ordinary same-aggregate query at a time, and
-      # never needs the whole chain resolved up front the way a seal
-      # does.
-      #
       # @param field [String, Symbol] the query field path, such as `"client/region/name"`
       # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
       #   starts from
@@ -124,11 +69,6 @@ module Hecks
       # Resolves every hop of a field path in order, stopping with a reason at
       # the first one it cannot follow.
       #
-      # The whole chain, resolved — every hop's target found, in
-      # order — for the one caller that needs it all at once:
-      # `BluebookBuilder#validate_query_hops!`, checking a hop chain
-      # before anything ever dispatches it.
-      #
       # @param field [String, Symbol] the query field path, such as `"client/region/name"`
       # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
       #   starts from
@@ -149,12 +89,8 @@ module Hecks
           hop, rest = step
           return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
 
-          # Pushed even unresolved — a caller reporting :unresolvable
-          # needs this hop's own target_name (real, known at
-          # declaration, regardless of whether resolve succeeded), not
-          # whatever hop came before it. `.target` is nil on this one
-          # entry; every caller checking `hops.last.target` already has
-          # to handle that, the same way `next_hop`'s own caller does.
+          # Pushed even unresolved: a caller reporting :unresolvable needs this hop's
+          # target_name, and `.target` is nil on this one entry.
           hops << hop
           return Plan.new(hops: hops, tail: nil, refusal: :unresolvable) unless hop.target
 

data/lib/hecks/release/gem_pin.rb

@@ -2,32 +2,8 @@ require_relative "gem_pin/published_versions"
 
 module Hecks
   module Release
-    # Finds the hecks version a project runs on, and refuses one that a
-    # stranger could not install.
-    #
-    # ## Why it exists
-    #
-    # A project that is copied out of its own workspace (handed to someone who
-    # will `bundle install` it, or built in an image with no sibling checkout)
-    # has to name a hecks release RubyGems actually publishes. A `path:` or
-    # `git:` source only works where the path or remote is reachable, and a
-    # version that was never published resolves nowhere. This reads the
-    # project's Gemfiles and lockfiles, without running Bundler, and says which
-    # version each pins or refuses.
-    #
-    # ## Resolution
-    #
-    # For each `Gemfile` under the root (a project can hold several, such as a
-    # domain and a helper app) the pin is, in order: the version its
-    # `Gemfile.lock` resolved, or the newest stable release its version
-    # constraint allows. Each pin must be published; the Gemfiles need not
-    # agree.
-    #
-    # ## Injectable network
-    #
-    # The published list comes from `published:`, any object answering
-    # `include?(version)` and `newest_satisfying(requirement)`. The default asks
-    # RubyGems; a caller without network hands in its own.
+    # Reads a project's Gemfiles and lockfiles (no Bundler run) and says which
+    # hecks version each pins, refusing any version RubyGems does not publish.
     class GemPin
       GEM_LINE = /^\s*gem\s+["']hecks["'](?<rest>.*)$/
       SOURCE_OPTION = /\b(?:path|git|github|gitlab|bitbucket|branch|ref|tag):/

data/lib/hecks/release/runner/ci_publisher.rb

@@ -3,13 +3,10 @@ require_relative "commands"
 module Hecks
   module Release
     class Runner
-      # The npm step when CI publishes: the release tag triggers
-      # `.github/workflows/publish-client.yml`, which publishes `@hecks/client`
-      # with npm trusted publishing, so nothing is published from this machine.
-      # This watches npm until the version appears.
+      # Watches npm for `@hecks/client` after CI publishes it via
+      # `.github/workflows/publish-client.yml` (npm trusted publishing).
       #
-      # The clock and the pause are injected, so a spec runs the whole wait
-      # without sleeping.
+      # Its clock and pause are injected, so a spec runs the wait without sleeping.
       class CiPublisher
         WORKFLOW = ".github/workflows/publish-client.yml".freeze
         INTERVAL = 15

data/lib/hecks/release/runner/commands.rb

@@ -9,10 +9,8 @@ module Hecks
       # Raised when a check refuses the release; the message names the fix.
       class Refusal < StandardError; end
 
-      # Runs the release's external commands: git, gem, npm, curl, op.
-      #
-      # The runner takes any object answering `capture` and `run!` the way this
-      # one does, so a spec hands in a recorder and never starts a real process.
+      # Runs the release's external commands (git, gem, npm, curl, op) through
+      # any object answering `capture`/`run!`, so a spec injects a recorder.
       class Commands
         # What a captured command printed and whether it succeeded.
         #

data/lib/hecks/release/runner/gem_publisher.rb

@@ -4,9 +4,8 @@ require_relative "commands"
 module Hecks
   module Release
     class Runner
-      # The gem step: hands the push to `bin/release_gem`, which owns building the
-      # gem and pushing it with the key 1Password holds. A dry run builds the gem
-      # to prove it builds and deletes it.
+      # The gem step: hands the push to `bin/release_gem`, which builds and pushes
+      # it with the key 1Password holds; a dry run only builds it, then deletes it.
       class GemPublisher
         # @param root [String] the repository root
         # @param commands [#run!] runs the build and the push

data/lib/hecks/release/runner/npm_publisher.rb

@@ -6,17 +6,6 @@ module Hecks
     class Runner
       # The npm step: publishes `@hecks/client` from `packages/hecks-client`
       # with the token 1Password holds.
-      #
-      # `op run` resolves `release/npm_publish.env` into the environment of the
-      # one `npm publish` process. npm reads its token from a config file, so a
-      # throwaway user config holds a placeholder that npm expands from that
-      # environment; the file never contains the token and is deleted afterwards.
-      # The package's `prepack` builds `dist/`.
-      #
-      # The token is a granular one that bypasses two-factor authentication, because
-      # the account's second factor is a passkey. As a fallback the publish runs with
-      # `--auth-type=web` and its output is not captured, so if npm does ask for an
-      # approval it prints the link straight to the terminal and waits for it.
       class NpmPublisher
         PACKAGE_DIR = "packages/hecks-client".freeze
         ENV_FILE = "release/npm_publish.env".freeze
@@ -24,21 +13,14 @@ module Hecks
                           "This step waits for you.".freeze
         USERCONFIG_LINE = "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}".freeze
 
-        # @param root [String] the repository root
-        # @param commands [#run!] runs npm and op
-        # @param console [Console] progress output
         def initialize(root:, commands:, console:)
           @root = root
           @commands = commands
           @console = console
         end
 
-        # Publishes the package, or with `dry_run` only packs it.
-        #
-        # @param version [String] the version being released
-        # @param dry_run [Boolean] run `npm publish --dry-run`, which needs no credentials
-        # @return [void]
-        # @raise [CommandFailed] if installing, building or publishing fails
+        # Publishes the package, or with `dry_run` only packs it, which needs no
+        # credentials.
         def publish!(version, dry_run:)
           install_dependencies
           if dry_run
@@ -57,6 +39,7 @@ module Hecks
           File.join(@root, PACKAGE_DIR)
         end
 
+        # npm's `prepack` hook builds `dist/`; there is no separate build step here.
         def install_dependencies
           return if Dir.exist?(File.join(package_dir, "node_modules"))
 
@@ -64,6 +47,9 @@ module Hecks
           @commands.run!("npm", "ci", chdir: package_dir)
         end
 
+        # The token bypasses 2FA (the account's second factor is a passkey); this
+        # fallback publish runs with `--auth-type=web` and doesn't capture output,
+        # so an approval prompt reaches the terminal.
         def publish_with_token
           with_userconfig do |userconfig|
             @commands.run!(