hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/expression/evaluator.rb

@@ -16,9 +16,9 @@ module Hecks
 
         # Six operators, reduced to two primitives (less_than, equal) combined
         # with a small boolean algebra: compares_less_than/compares_equal choose
-        # which primitive(s) OR together, negated inverts the result.
+        # which primitive(s) or together, negated inverts the result.
         #
-        # READ, NOT RESTATED. This table is the checked-in projection of the
+        # **Read, not restated**. This table is the checked-in projection of the
         # grammar chapter's admitted set (bin/expression_projection), joined with
         # the algebra Vocabulary::Comparison declares. The evaluator cannot
         # boot the chapter that configures it — the Prism adapter normalises
@@ -53,20 +53,37 @@ module Hecks
 
         module_function
 
-        # Keyed by the exact string `call` receives. Canonical text is already
+        # Memoizes each distinct predicate string's own parsed AST, keyed by
+        # the exact string `call` receives. Canonical text is already
         # normalised at DSL-build time, so the same given/invariant's text is
         # byte-identical across every dispatch that evaluates it — parsed once
         # here, interpreted fresh against each call's own state/attrs. Matches
         # MetaValidator.verdicts' unsynchronized `||= {}` idiom : redundant
         # parse work under real parallelism, never corruption.
+        #
+        # @return [Hash{String => Object}] the process-wide parse cache,
+        #   keyed by predicate string; each value is one of `Or`, `And`,
+        #   `Not`, `Compare`, `Include`, or `Resolve`
         def ast_cache = @ast_cache ||= {}
 
+        # Parses `expr` (cached per distinct string) and interprets it
+        # against `state`/`attrs`.
+        #
+        # @param expr [String] the canonical predicate text to evaluate
+        # @param state [Hash{Symbol => Object}] the stored attribute values
+        #   a `Resolve`/`Compare` leaf may resolve against
+        # @param attrs [Hash{Symbol => Object}] the call's own argument
+        #   values, checked before `state`
+        # @return [Boolean] whether `expr` holds
+        # @raise [EvaluationError] if `expr` resolves an unknown attribute
+        #   or argument, or applies an operation to a value of the wrong
+        #   type
         def call(expr, state, attrs = {})
           interpret(ast_cache[expr] ||= parse(expr), state, attrs)
         end
 
-        # THE RULE-SHAPED ENTRY — evaluates a Given/Invariant (anything
-        # answering `canonical` and `ast`) by walking its STRUCTURED form,
+        # The rule-shaped entry — evaluates a Given/Invariant (anything
+        # answering `canonical` and `ast`) by walking its structured form,
         # never re-parsing the text: the one parse happened at DSL-build
         # time behind `AstJson`, and `AstReader` turns that tree back into
         # the same nodes `parse` would have built (the equivalence is
@@ -77,31 +94,60 @@ module Hecks
         #
         # HECKS_EVAL=string reverts to the text path wholesale, kept for
         # one release as the escape hatch while the ast path beds in.
+        #
+        # @param rule [Bluebook::Given, Bluebook::Invariant] the rule to
+        #   evaluate
+        # @param state [Hash{Symbol => Object}] the stored attribute values
+        #   a `Resolve`/`Compare` leaf may resolve against
+        # @param attrs [Hash{Symbol => Object}] the call's own argument
+        #   values, checked before `state`
+        # @return [Boolean] whether `rule` holds
+        # @raise [EvaluationError] if `rule` resolves an unknown attribute
+        #   or argument, or applies an operation to a value of the wrong
+        #   type
         def call_rule(rule, state, attrs = {})
           return call(rule.canonical, state, attrs) if ENV["HECKS_EVAL"] == "string"
 
           interpret(ast_cache[rule.canonical] ||= nodes_for(rule), state, attrs)
         end
 
+        # Returns `rule`'s own AST, read back from its `ast` field when
+        # present, otherwise parsed fresh from `canonical`.
+        #
+        # @param rule [Bluebook::Given, Bluebook::Invariant] the rule to
+        #   read
+        # @return [Object] one of `Or`, `And`, `Not`, `Compare`, `Include`,
+        #   or `Resolve`
         def nodes_for(rule)
           rule.ast ? AstReader.read_predicate(rule.ast) : parse(rule.canonical)
         end
 
-        # A refused `given`/`ensures`/`invariant` names its own DESCRIPTION
-        # ("not already superseded") but, on its own, not what the block
-        # actually evaluated to — the difference between "the rule is right
-        # and my data is wrong" and "the rule is subtly wrong" is often just
-        # seeing the two operands. Scoped to the single shape that has one
-        # honest answer: `expr`'s own TOP-LEVEL node is a bare `Compare` —
-        # not `Or`/`And`/`Not` (which of several sub-comparisons would even
-        # be "the" one at fault is genuinely ambiguous), `Include` (no
-        # left/right to show), or `Resolve` (a bare boolean read, nothing to
-        # compare against). Values are rendered with `Rendering.describe`,
-        # the same house style every other refusal already prints a value
-        # through. Returns `nil` — not raised — on anything else, INCLUDING
-        # an operand that itself fails to resolve (`EvaluationError`): a
+        # Renders `expr`'s own two operands, for a refusal message to show
+        # alongside a failed `given`/`ensures`/`invariant`. A refused rule
+        # names its own description ("not already superseded") but, on its
+        # own, not what the block actually evaluated to — the difference
+        # between "the rule is right and my data is wrong" and "the rule
+        # is subtly wrong" is often just seeing the two operands. Scoped
+        # to the single shape that has one honest answer: `expr`'s own
+        # top-level node is a bare `Compare` — not `Or`/`And`/`Not` (which
+        # of several sub-comparisons would even be "the" one at fault is
+        # genuinely ambiguous), `Include` (no left/right to show), or
+        # `Resolve` (a bare boolean read, nothing to compare against).
+        # Values are rendered with `Rendering.describe`, the same house
+        # style every other refusal already prints a value through.
+        # Returns `nil` — not raised — on anything else, including an
+        # operand that itself fails to resolve (`EvaluationError`): a
         # missing diagnostic is a worse debugging experience than none, a
         # crash while building one is worse still.
+        #
+        # @param expr [String] the canonical predicate text that was just
+        #   refused
+        # @param state [Hash{Symbol => Object}] the stored attribute values
+        #   the operands may resolve against
+        # @param attrs [Hash{Symbol => Object}] the call's own argument
+        #   values, checked before `state`
+        # @return [String, nil] `"left: X, right: Y"` when `expr` is a bare
+        #   comparison whose operands both resolve; `nil` otherwise
         def comparison_detail(expr, state, attrs = {})
           node = ast_cache[expr] ||= parse(expr)
           return nil unless node.is_a?(Compare)
@@ -113,6 +159,12 @@ module Hecks
           nil
         end
 
+        # Parses `expr`'s boolean/comparison grammar into an AST, recursing
+        # into `Resolver.parse` for each leaf.
+        #
+        # @param expr [String] the canonical predicate text to parse
+        # @return [Object] one of `Or`, `And`, `Not`, `Compare`, `Include`,
+        #   or `Resolve`, chosen by `expr`'s own shape
         def parse(expr)
           expr = strip_parens(expr.to_s.strip)
 
@@ -122,18 +174,18 @@ module Hecks
           left, right = split_top_level(expr, "&&")
           return And.new(left: parse(left), right: parse(right)) if left
 
-          # Tried BEFORE `.include?`/comparisons, not after — `!` negates
-          # the WHOLE boolean expression that follows it (`!names.include?(x)`
+          # Tried before `.include?`/comparisons, not after — `!` negates
+          # the whole boolean expression that follows it (`!names.include?(x)`
           # means `!(names.include?(x))`, never "call .include? on the negated
           # receiver"), so the leading marker has to be stripped and the
           # remainder re-parsed before anything downstream gets a chance to
-          # mis-scan across it. It used to sit after `match_include`, whose
+          # mis-scan across it. Tried after `match_include` instead, its
           # naive `rindex(".include?(")` has no concept of a leading `!` —
-          # for `!names.include?(x)` it swallowed the `!` straight into the
-          # haystack text ("!names"), which `Resolver.parse` cannot resolve,
-          # so every spelling of negated membership raised instead of
-          # evaluating. Moving the check here fixes both the bare prefix
-          # (`!names.include?(x)`) and the parenthesized form
+          # for `!names.include?(x)` it would swallow the `!` straight into
+          # the haystack text ("!names"), which `Resolver.parse` cannot
+          # resolve, so every spelling of negated membership would raise
+          # instead of evaluating. Checking here first fixes both the bare
+          # prefix (`!names.include?(x)`) and the parenthesized form
           # (`!(names.include?(x))`) — the recursive `parse` call sees the
           # clean remainder and correctly finds the `.include?` (or `&&`/`||`)
           # inside it.
@@ -150,6 +202,19 @@ module Hecks
           Resolve.new(expr: Resolver.parse(expr))
         end
 
+        # Interprets a parsed boolean/comparison node against `state`/
+        # `attrs`.
+        #
+        # @param node [Object] a node `parse` produced (`Or`, `And`, `Not`,
+        #   `Compare`, `Include`, or `Resolve`)
+        # @param state [Hash{Symbol => Object}] the stored attribute values
+        #   a leaf may resolve against
+        # @param attrs [Hash{Symbol => Object}] the call's own argument
+        #   values, checked before `state`
+        # @return [Boolean] whether `node` holds
+        # @raise [EvaluationError] if `node` is not one of the handled
+        #   types, or a leaf it delegates to (`compare`, `includes?`,
+        #   `Resolver.interpret`) refuses its operand
         def interpret(node, state, attrs)
           case node
           when Or      then interpret(node.left, state, attrs) || interpret(node.right, state, attrs)
@@ -162,16 +227,30 @@ module Hecks
             # Every node `parse` can produce has a `when` above — a
             # backstop against the day this grammar grows a new node
             # type and `interpret` doesn't grow to match it. A missing
-            # arm here used to return bare `nil`, and `Or`/`And` fold
-            # that straight into the boolean algebra as ordinary falsy
-            # — reading exactly like "the rule legitimately does not
-            # hold" rather than "the runtime cannot evaluate this rule
-            # at all", the one silent no-op this language otherwise
+            # arm here would instead return bare `nil`, and `Or`/`And`
+            # fold that straight into the boolean algebra as ordinary
+            # falsy — reading exactly like "the rule legitimately does
+            # not hold" rather than "the runtime cannot evaluate this
+            # rule at all", the one silent no-op this language otherwise
             # refuses.
             raise EvaluationError, "no interpreter handles #{node.class} — add a case before parse can produce it"
           end
         end
 
+        # Resolves `left`/`right` and applies `comparator` to the results.
+        #
+        # @param comparator [Operator] the comparison operator to apply
+        # @param left [Object] a `Resolver` leaf node (`Resolver.parse`'s
+        #   own return) for the left operand
+        # @param right [Object] a `Resolver` leaf node (`Resolver.parse`'s
+        #   own return) for the right operand
+        # @param state [Hash{Symbol => Object}] the stored attribute values
+        #   the operands may resolve against
+        # @param attrs [Hash{Symbol => Object}] the call's own argument
+        #   values, checked before `state`
+        # @return [Boolean] the comparison's result
+        # @raise [EvaluationError] if an operand does not resolve, or
+        #   `less_than`/`equal?` cannot compare the resolved values
         def compare(comparator, left, right, state, attrs)
           lhs = Resolver.interpret(left, state, attrs)
           rhs = Resolver.interpret(right, state, attrs)
@@ -181,14 +260,29 @@ module Hecks
 
         # The algebra itself, on values already resolved — split out so a sign
         # test (SignTest#compares_via names an Operator symbol) can apply the
-        # SAME primitives compare() uses against the literal 0, rather than
+        # same primitives compare() uses against the literal 0, rather than
         # re-deriving positive?/negative?/zero? by hand a second time.
+        #
+        # @param comparator [Operator] the comparison operator to apply
+        # @param lhs [Object] the already-resolved left operand
+        # @param rhs [Object] the already-resolved right operand
+        # @return [Boolean] `comparator`'s result over `lhs`/`rhs`
+        # @raise [EvaluationError] if `comparator` tests less-than and
+        #   `lhs`/`rhs` are not both numeric or both String
         def apply(comparator, lhs, rhs)
           result = (comparator.compares_less_than && less_than(lhs, rhs)) ||
                    (comparator.compares_equal && equal?(lhs, rhs))
           comparator.negated ? !result : result
         end
 
+        # Compares two already-resolved operands for the `<` primitive.
+        #
+        # @param lhs [Object] the already-resolved left operand
+        # @param rhs [Object] the already-resolved right operand
+        # @return [Boolean] whether `lhs` is less than `rhs`, comparing
+        #   numerically if both are numeric, lexically if both are String
+        # @raise [EvaluationError] if `lhs`/`rhs` are not both numeric or
+        #   both String
         def less_than(lhs, rhs)
           left  = Resolver.numeric(lhs)
           right = Resolver.numeric(rhs)
@@ -199,6 +293,12 @@ module Hecks
                 "comparison of #{class_of(lhs)} with #{Resolver.describe(rhs)} failed"
         end
 
+        # Compares two already-resolved operands for the `equal` primitive.
+        #
+        # @param lhs [Object] the already-resolved left operand
+        # @param rhs [Object] the already-resolved right operand
+        # @return [Boolean] whether `lhs` equals `rhs`, comparing
+        #   numerically if both are numeric, `==` otherwise
         def equal?(lhs, rhs)
           left  = Resolver.numeric(lhs)
           right = Resolver.numeric(rhs)
@@ -207,26 +307,42 @@ module Hecks
           lhs == rhs
         end
 
+        # Reports whether `value` is truthy, for a bare `Resolve` node.
+        #
+        # @param value [Object] the value to test
+        # @return [Boolean] Ruby's own truthiness: `false` for `nil` and
+        #   `false`, `true` for everything else
         def truthy?(value)
           !value.nil? && value != false
         end
 
+        # Names `value`'s class, for a refusal message.
+        #
+        # @param value [Object] the value to name
+        # @return [String] `"nil"` for `nil`, otherwise `value.class.name`
         def class_of(value)
           value.nil? ? "nil" : value.class.name
         end
 
-        # THE SAME MIS-SPLIT `Resolver.match_call` had (its own comment
+        # The same mis-split `Resolver.match_call` had (its own comment
         # has the full story), found here too by the same generator: a
-        # `.include?` needle can itself be — or contain — ANOTHER
+        # `.include?` needle can itself be — or contain — another
         # `.include?` call (`"".include?(arr.all? { |el| "".include?("")
         # }.to_s)`, a String built via `.to_s` off a block predicate
         # whose own body happens to include one) — `rindex` finds the
-        # INNERMOST occurrence, not the outermost this split actually
+        # innermost occurrence, not the outermost this split actually
         # needs. Fixed identically: try each occurrence left to right,
         # keep the first whose own balanced-paren match reaches the
         # string's last character — `Resolver.matching_paren` is reused
         # directly rather than duplicated, the same depth-tracking rule
         # either grammar layer needs here.
+        # Splits `expr` at its outermost `.include?(...)` call, if any.
+        #
+        # @param expr [String] the boolean-position expression text
+        # @return [Array(String, String), nil] the `[haystack_text,
+        #   needle_text]` pair for the outermost `.include?(` occurrence
+        #   whose matching close paren reaches `expr`'s last character, or
+        #   `nil` if none does
         def match_include(expr)
           start = 0
           marker = ".include?("
@@ -246,6 +362,19 @@ module Hecks
         # does.
         INCLUDE_HAYSTACKS = Hecks::Vocabulary.fetch("IncludeHaystack")
 
+        # Resolves and evaluates an `Include` node's own `.include?` test.
+        #
+        # @param parts [Array(Object, Object)] the `[haystack, needle]`
+        #   pair of `Resolver` leaf nodes from `Include#haystack`/`#needle`
+        # @param state [Hash{Symbol => Object}] the stored attribute values
+        #   the operands may resolve against
+        # @param attrs [Hash{Symbol => Object}] the call's own argument
+        #   values, checked before `state`
+        # @return [Boolean] whether the resolved haystack includes the
+        #   resolved needle (`equal?`-compared for an Array, `#include?`
+        #   for a String); `false` for any other resolved haystack type
+        # @raise [EvaluationError] if the haystack resolves to a String and
+        #   the needle does not
         def includes?(parts, state, attrs)
           haystack, needle = parts
           wanted = Resolver.interpret(needle, state, attrs)
@@ -260,6 +389,11 @@ module Hecks
           end
         end
 
+        # Strips a redundant outer pair of parens, recursively.
+        #
+        # @param expr [String] the expression text
+        # @return [String] `expr` with every redundant outer `(...)` pair
+        #   removed; `expr` unchanged if it is not wholly parenthesized
         def strip_parens(expr)
           return expr unless expr.start_with?("(") && expr.end_with?(")")
 
@@ -272,6 +406,14 @@ module Hecks
           strip_parens(expr[1..-2].strip)
         end
 
+        # Splits `expr` at its first top-level occurrence of `operator`.
+        #
+        # @param expr [String] the expression text
+        # @param operator [String] the operator text to split on, such as
+        #   `"||"` or `"&&"`
+        # @return [Array(String, String), nil] the `[left, right]` operand
+        #   text around the split, or `nil` if `expr` has no top-level
+        #   occurrence
         def split_top_level(expr, operator)
           index = top_level_index(expr, operator)
           return nil unless index
@@ -279,6 +421,17 @@ module Hecks
           [expr[0...index].strip, expr[(index + operator.length)..].strip]
         end
 
+        # Splits `expr` at its first top-level occurrence of `operator`
+        # that is not part of a longer operator's own spelling (`==` is
+        # not mistaken for the middle of `===`, `<` is not mistaken for
+        # the leading `<` of `<=`).
+        #
+        # @param expr [String] the expression text
+        # @param operator [String] the comparison operator text to split
+        #   on, such as `"=="` or `"<"`
+        # @return [Array(String, String), nil] the `[left, right]` operand
+        #   text around the split, or `nil` if `expr` has no matching
+        #   top-level occurrence
         def split_comparison(expr, operator)
           index = top_level_index(expr, operator) { |at| !part_of_longer?(expr, at, operator) }
           return nil unless index
@@ -286,6 +439,15 @@ module Hecks
           [expr[0...index].strip, expr[(index + operator.length)..].strip]
         end
 
+        # Reports whether the occurrence of `operator` at `index` is
+        # actually the middle of a longer operator's own spelling (`==`
+        # inside `===`, or `<`/`>`/`!`/`=` immediately before a bare `=`).
+        #
+        # @param expr [String] the expression text
+        # @param index [Integer] the index of the candidate occurrence
+        # @param operator [String] the operator text being tried
+        # @return [Boolean] whether this occurrence belongs to a longer
+        #   operator and should be skipped
         def part_of_longer?(expr, index, operator)
           after  = expr[index + operator.length]
           before = index.positive? ? expr[index - 1] : nil
@@ -296,6 +458,21 @@ module Hecks
           false
         end
 
+        # A grammar's own depth-aware scanner, shared by `split_top_level`/
+        # `split_comparison` — one pass finds the first top-level
+        # occurrence of `operator`, tracking quotes and every bracket
+        # kind (`(`/`)`, `{`/`}`, `[`/`]`) so an operator inside a nested
+        # call, block predicate, or array literal is never mistaken for a
+        # split point at this level.
+        #
+        # @param expr [String] the expression text
+        # @param operator [String] the operator text to search for
+        # @yieldparam index [Integer] a candidate top-level occurrence's
+        #   index, offered so the caller can reject it (`split_comparison`
+        #   uses this to skip a longer operator's own spelling)
+        # @yieldreturn [Boolean] whether to accept this occurrence
+        # @return [Integer, nil] the accepted occurrence's index, or `nil`
+        #   if `operator` has no top-level occurrence the block accepts
         def top_level_index(expr, operator)
           depth = 0
           quote = nil
@@ -311,13 +488,13 @@ module Hecks
             # `{`/`}` depth -- vendored addition, not (yet) upstream
             # hecks (migration plan task 9): this method already
             # treats `(`/`)` as a grouping construct so an operator
-            # INSIDE a call's parens is never mistaken for a top-level
+            # inside a call's parens is never mistaken for a top-level
             # split point ; `{`/`}` needed the identical treatment the
             # moment `Bluebook::Expression::Resolver` grew block-taking
             # `.all?`/`.any?`/`.none? { |s| PREDICATE }` support (see
             # resolver.rb's own `BlockPredicate` addition) -- without
-            # this, an operator INSIDE the block's own predicate (e.g.
-            # `s.length > 0`) reads as a top-level split of the WHOLE
+            # this, an operator inside the block's own predicate (e.g.
+            # `s.length > 0`) reads as a top-level split of the whole
             # `value.split("::").all? { |s| s.length > 0 }` expression,
             # confirmed live via `Lexicon::Lexicon.Lookup`/`Query::Query.
             # Run` (the exact `Phrase` invariant this gap was found
@@ -329,16 +506,17 @@ module Hecks
             # a quoted literal either, so this sits beside the existing
             # paren-depth branch, not instead of it.
             #
-            # `[`/`]` -- the identical lesson a THIRD time (found live via
+            # `[`/`]` -- the identical lesson a third time (found live via
             # the type-directed bounded-exhaustive expression generator,
             # Phase 7 of the equivalence-gap plan): `Resolver::ArrayLiteral`
             # (`[a, b]`) can appear as a general sub-expression, not only
             # as `.include?`'s own haystack, the moment an array-typed
             # attribute or a synthesized literal is embedded anywhere else
-            # -- and an element containing a top-level `+`/comparison of
-            # its own (`[0, 0 + 0]`) used to read as a split point for
-            # THIS expression's own boolean/comparison grammar, exactly
-            # the way an un-tracked `{`/`}` once did for block predicates.
+            # -- so without counting `[`/`]` toward depth here too, an
+            # element containing a top-level `+`/comparison of its own
+            # (`[0, 0 + 0]`) reads as a split point for this expression's
+            # own boolean/comparison grammar, exactly the way an
+            # un-tracked `{`/`}` does for block predicates.
             elsif ["(", "{", "["].include?(char)
               depth += 1
             elsif [")", "}", "]"].include?(char)

data/lib/hecks/bluebook/expression/resolver/block_predicates.rb

@@ -1,7 +1,7 @@
-# HAND-WRITTEN — the block-predicate/find family of the leaf grammar
+# **Hand-written** — the block-predicate/find family of the leaf grammar
 # (`Bluebook::Expression::Resolver`'s own `.all?`/`.any?`/`.none?`/
 # `.find` suffixes), split into this sibling file to keep resolver.rb
-# under Metrics/ModuleLength (350) : this reopens the SAME `Resolver`
+# under Metrics/ModuleLength (350) : this reopens the same `Resolver`
 # module resolver.rb defines, the long nested `module A; module B; ...`
 # form (not the compact `A::B` form) so bare constant/method lookups
 # here (`EvaluationError`, `Evaluator`, `describe`, `unwrap_scalar`,
@@ -12,7 +12,7 @@
 module Hecks
   module Bluebook
     module Expression
-      # Reopens the SAME `Resolver` module resolver.rb defines — see this
+      # Reopens the same `Resolver` module resolver.rb defines — see this
       # file's own header comment above for why the block-predicate/find
       # family lives here rather than in resolver.rb itself.
       module Resolver
@@ -23,12 +23,12 @@ module Hecks
         # (`value.split("::").all? { |s| s.length > 0 }`). Structurally
         # different from every other addition in this file: every prior
         # suffix is a flat receiver -> scalar transform, but a block
-        # predicate needs to evaluate its own sub-expression ONCE PER
-        # ELEMENT with the block parameter bound to that element. Kept
+        # predicate needs to evaluate its own sub-expression once per
+        # element with the block parameter bound to that element. Kept
         # minimal per the migration plan's own instruction -- no
         # persistent iteration-variable concept added to Resolver's
         # state model at all ; `predicate` below is a fully-parsed
-        # EVALUATOR ast (not a Resolver ast -- the predicate is a
+        # evaluator ast (not a Resolver ast -- the predicate is a
         # boolean/comparison expression like `s.length > 0`, exactly the
         # grammar `Bluebook::Expression::Evaluator` owns, not this
         # module's own leaf grammar), parsed once at `parse`-time same as
@@ -78,7 +78,7 @@ module Hecks
 
         # Every suffix that opens a `{ |x| ... }` block, `.find` included
         # -- shared by `parse_block_opener` below, and by nothing else
-        # (this is NOT `BLOCK_PREDICATE_MODES` — `.find` isn't a mode
+        # (this is not `BLOCK_PREDICATE_MODES` — `.find` isn't a mode
         # `evaluate_block_predicate` aggregates through, it builds a
         # `Find` node instead, see below).
         BLOCK_OPENER_SUFFIXES = (BLOCK_PREDICATE_MODES.keys + ["find"]).freeze
@@ -88,27 +88,27 @@ module Hecks
         # last among the suffix rules (right before the `Lookup`
         # catch-all) since a block's own predicate text can itself
         # contain almost anything a leaf expression can, including
-        # ANOTHER block-opening suffix -- letting every more specific
+        # another block-opening suffix -- letting every more specific
         # rule above try first avoids this one accidentally swallowing a
         # receiver another rule was meant to parse.
         #
-        # ONE combined header regex over ALL FOUR suffixes together,
+        # One combined header regex over all four suffixes together,
         # not `.find` and `.all?/any?/none?` scanned separately (that
         # was this file's own first cut, and it broke the moment a
-        # block predicate's own predicate text contained a DIFFERENT
+        # block predicate's own predicate text contained a different
         # kind of block-opener than the one being scanned for --
         # `legs.any? { |leg| ... legs.find { |o| ... } ... }` : scanning
-        # for `.find` FIRST found the INNER `.find`, not the outer
+        # for `.find` first found the inner `.find`, not the outer
         # `.any?`, because a non-greedy receiver capture only guarantees
-        # the FIRST occurrence of ITS OWN suffix, not the first
-        # occurrence of ANY block-opening suffix -- confirmed live via
+        # the first occurrence of its own suffix, not the first
+        # occurrence of any block-opening suffix -- confirmed live via
         # the shipping domain's own re-routing rules, the same
         # "no implicit conversion of Symbol into Integer" signature the
         # original nested-`.any?` bug had, not inferred). Scanning for
-        # all four AT ONCE and letting the regex engine's own leftmost
-        # match win fixes both directions (`.find` nested in `.any?` OR
-        # `.any?` nested in `.find`) with the SAME one rule, since the
-        # true receiver never itself contains ANY of these four words
+        # all four at once and letting the regex engine's own leftmost
+        # match win fixes both directions (`.find` nested in `.any?` or
+        # `.any?` nested in `.find`) with the same one rule, since the
+        # true receiver never itself contains any of these four words
         # followed by `{`.
         #
         # `matching_brace` walks forward counting `{`/`}` depth from
@@ -119,6 +119,10 @@ module Hecks
         # is captured from whatever follows the closing brace ; every
         # other suffix instead requires nothing follow it at all (the
         # `BlockPredicate` shape, unchanged from before this rewrite).
+        #
+        # @param expr [String] the leaf expression text to parse
+        # @return [Find, BlockPredicate, nil] the parsed node, or nil when `expr` does
+        #   not open a `.all?`/`.any?`/`.none?`/`.find` block, or its brace never closes
         def parse_block_opener(expr)
           pattern = /\A(.+?)\.(#{BLOCK_OPENER_SUFFIXES.map { |suffix| Regexp.escape(suffix) }.join('|')})\s*\{\s*\|(\w+)\|\s*/m
           header = expr.match(pattern)
@@ -155,6 +159,11 @@ module Hecks
         # quoted substring (`.start_with?("}")`) never miscounts, the
         # same discipline `split_addition`/`array_elements` already
         # apply for their own depth tracking.
+        #
+        # @param expr [String] the text to scan
+        # @param start [Integer] the index just after the opening `{`, where depth is 1
+        # @return [Integer, nil] the index of the matching `}`, or nil if `expr` runs
+        #   out before depth returns to 0
         def matching_brace(expr, start)
           depth = 1
           quote = nil
@@ -186,6 +195,13 @@ module Hecks
         # variable concept added anywhere else in Resolver's state model,
         # just `attrs` extended with the bound name for the span of that
         # one predicate evaluation, discarded immediately after.
+        #
+        # @param node [BlockPredicate] the parsed `.all?`/`.any?`/`.none?` node
+        # @param collection [Object] the interpreted receiver, expected to be an Array
+        # @param state [Hash{Symbol => Object}] the record's own current state
+        # @param attrs [Hash{Symbol => Object}] the command's own bound arguments
+        # @return [Boolean] whether the collection satisfies `node.mode`
+        # @raise [EvaluationError] if `collection` is not an Array
         def evaluate_block_predicate(node, collection, state, attrs)
           raise EvaluationError, "#{node.mode}? expects a list, got #{describe(collection)}" unless collection.is_a?(Array)
 
@@ -202,6 +218,18 @@ module Hecks
         # evaluation -- `attrs` wins over `state` in `fetch` (see below),
         # so the bound name shadows any same-named state/attrs field for
         # the span of this one call only ; nothing persists past it.
+        #
+        # @param node [BlockPredicate, Find] the node whose `param`/
+        #   `predicate` to bind and interpret
+        # @param element [Object] the one collection element to bind
+        #   `node.param` to
+        # @param state [Hash{Symbol => Object}] the record's own current
+        #   state
+        # @param attrs [Hash{Symbol => Object}] the command's own bound
+        #   arguments
+        # @return [Object] `node.predicate` interpreted with `node.param`
+        #   bound to `element`
+        # @raise [EvaluationError] if `node.predicate` refuses to evaluate
         def interpret_with_element(node, element, state, attrs)
           Evaluator.interpret(node.predicate, state, attrs.merge(node.param.to_sym => element))
         end
@@ -210,7 +238,7 @@ module Hecks
         # comment above. Reuses `interpret_with_element` unchanged
         # (below, shared with `BlockPredicate` — both bind `node.param`
         # to one element and interpret `node.predicate` against it) to
-        # find the FIRST element the predicate accepts, then projects
+        # find the first element the predicate accepts, then projects
         # `node.path` through it via `walk_path`, the same dotted-
         # segment walk `lookup` uses for a plain attribute path. `nil`
         # (no matching element, or a `path` segment that doesn't
@@ -219,6 +247,14 @@ module Hecks
         # value case in this grammar already has, and the one a re-
         # routing check like "is there a leg after this one" needs :
         # not finding one is a normal outcome, not an error.
+        #
+        # @param node [Find] the parsed `.find` node
+        # @param collection [Object] the interpreted receiver, expected to be an Array
+        # @param state [Hash{Symbol => Object}] the record's own current state
+        # @param attrs [Hash{Symbol => Object}] the command's own bound arguments
+        # @return [Object, nil] the found element (or `node.path` projected through it),
+        #   or nil when no element matches or a `path` segment does not resolve
+        # @raise [EvaluationError] if `collection` is not an Array
         def found_of(node, collection, state, attrs)
           raise EvaluationError, "find expects a list, got #{describe(collection)}" unless collection.is_a?(Array)