hecks 1.4.0 → 1.5.0

data/lib/hecks/bluebook/dsl/value_object_builder.rb

@@ -16,6 +16,10 @@ module Hecks
         include RuleReference
         include WordGate
 
+        # @param name [String] the value object's name, as written after `value_object`
+        # @param owner_value_objects [Array<Bluebook::ValueObject>] the owning aggregate's other
+        #   value objects, built so far, that this one's `invariant` references may resolve
+        #   against
         def initialize(name, owner_value_objects: [])
           @name       = name
           @invariants = []
@@ -46,7 +50,11 @@ module Hecks
         # still needs to read it. `block_given?` is what tells the two
         # calling shapes apart: the type-position form
         # (`one_of("a", "b")`) never passes a block, only the wrapper does.
-        # Renamed from `one_of` — item #13's full metaprogrammed dispatch
+        # Declares this value object as a closed set, either from bare values or (under
+        # shadow-parsing) a legacy `do ... end` wrapper of `member` lines.
+        #
+        # Answers the `one_of` word through the table's `calls:` column —
+        # item #13's full metaprogrammed dispatch
         # (slice 5). Same name as `AttributeCollector#one_of_impl`'s own
         # — required for the `super(*values)` call below to keep
         # resolving; see that method's own comment. Reached directly
@@ -54,6 +62,13 @@ module Hecks
         # block-wrapper form has its own row, distinct from "Type"'s),
         # not through the Type-position fallback this word's other
         # context uses.
+        #
+        # @param values [Array<String, Symbol>] permitted values, given bare (no block); at
+        #   least one is required
+        # @yield a legacy `member` wrapper body; only read under shadow-parsing
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if given no values and no block, or a block outside
+        #   shadow-parsing
         def one_of_impl(*values, &block)
           unless block
             # No values, no block is the scalar spelling — nonsensical, not
@@ -83,9 +98,16 @@ module Hecks
           instance_eval(&block)
         end
 
-        # Renamed from `member` — item #13's full metaprogrammed dispatch
-        # (slice 4c). Bootstrap-reachable, in
-        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        # Declares one member row of a closed set, one value per attribute.
+        #
+        # Answers the `member` word through the table's `calls:` column —
+        # item #13's full metaprogrammed dispatch (slice 4c). Bootstrap-reachable, in
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
+        #
+        # @param fields [Hash{Symbol => Object}] each declared attribute's name mapped to this
+        #   member's value for it
+        # @return [Array<Hash{Symbol => Object}>] every member declared so far, this one last
+        # @raise [Bluebook::DSL::Malformed] if `fields` is empty
         def member_impl(**fields)
           raise Malformed, "#{@name} declared an empty member" if fields.empty?
 
@@ -105,9 +127,20 @@ module Hecks
         # the referencing value object's own build time, against
         # whatever sibling value objects the aggregate has already
         # built, the same ordering rule `given` carries.
-        # Renamed from `invariant` — item #13's full metaprogrammed
-        # dispatch (slice 4b). Bootstrap-reachable, in
-        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        # Declares a rule this value object's own value must satisfy, or references one a sibling
+        # value object on the same aggregate already declared.
+        #
+        # Answers the `invariant` word through the table's `calls:` column —
+        # item #13's full metaprogrammed dispatch (slice 4b). Bootstrap-reachable, in
+        # `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
+        #
+        # @param description [String] the rule's description; also the name a sibling value
+        #   object references it by when no block is given
+        # @yield the predicate body; evaluated for its extracted source, never called directly
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if given a block whose source cannot be extracted or
+        #   uses a pattern construct engines disagree on, or given no block and no sibling value
+        #   object on this aggregate declares a rule with this description
         def invariant_impl(description, &predicate)
           return reference_named_invariant(description) unless predicate
 
@@ -134,6 +167,12 @@ module Hecks
 
         public
 
+        # Assembles the declared attributes, invariants and members into a `ValueObject`.
+        #
+        # @return [Bluebook::ValueObject] the built value object; `closed_set` is true when any
+        #   member was declared
+        # @raise [Bluebook::DSL::Malformed] if `one_of:` was declared on an attribute alongside
+        #   other attributes on the same value object
         def build
           if @inline_closed_set_field && attributes.size > 1
             raise Malformed,
@@ -149,6 +188,15 @@ module Hecks
           )
         end
 
+        # Evaluates a `value_object` block against a fresh builder and returns what it built.
+        #
+        # @param name [String] the value object's name
+        # @param owner_value_objects [Array<Bluebook::ValueObject>] the owning aggregate's other
+        #   value objects, for `invariant` references to resolve against
+        # @yield the value object body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::ValueObject] the built value object
+        # @raise [Bluebook::DSL::Malformed] if the body declares a rule extraction cannot read,
+        #   `one_of:` on more than one attribute, or uses a word the grammar does not admit
         def self.build(name, owner_value_objects: [], &block)
           builder = new(name, owner_value_objects: owner_value_objects)
           builder.instance_eval(&block) if block

data/lib/hecks/bluebook/entity.rb

@@ -70,6 +70,24 @@ module Hecks
         attr_reader :description, :identified_by, :identity_paths, :identity_heads,
                     :attributes, :commands, :queries, :entities, :preconditions, :invariants, :lifecycle
 
+        # Mints a new piece class for one declared entity and absorbs its fields into it.
+        #
+        # @param name [String, Symbol] the entity's declared name
+        # @param description [String, nil] the entity's declared prose description
+        # @param identified_by [String, Symbol, Array<String, Symbol>, nil] the identity
+        #   path(s) this entity is addressed by
+        # @param attributes [Array<Bluebook::Attribute>] the entity's declared fields
+        # @param commands [Array<Class>] the command classes (`Bluebook::Command` subclasses)
+        #   declared on this entity
+        # @param queries [Array<Bluebook::Query>] the queries declared on this entity
+        # @param entities [Array<Class>] the entity classes (`Bluebook::Entity` subclasses)
+        #   nested directly under this entity
+        # @param preconditions [Array<Bluebook::Given>] this entity's own named `given`s
+        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every
+        #   instance of this entity
+        # @param lifecycle [Bluebook::Lifecycle, nil] the entity's declared state machine,
+        #   or `nil` if it declares none
+        # @return [Class] the minted piece class (a `Bluebook::Entity` subclass)
         def declare(name:, description: nil, identified_by: nil, attributes: [],
                     commands: [], queries: [], entities: [], preconditions: [], invariants: [], lifecycle: nil)
           piece = Class.new(self)
@@ -85,6 +103,17 @@ module Hecks
         # Assigns what the language declares, then hands off to the
         # behaviour's own `settle` — derived identity and the name
         # indexes, neither of which the declaration states.
+        #
+        # @param description [String, nil] see `declare`
+        # @param identified_by [String, Symbol, Array<String, Symbol>, nil] see `declare`
+        # @param attributes [Array<Bluebook::Attribute>] see `declare`
+        # @param commands [Array<Class>] see `declare`
+        # @param queries [Array<Bluebook::Query>] see `declare`
+        # @param entities [Array<Class>] see `declare`
+        # @param preconditions [Array<Bluebook::Given>] see `declare`
+        # @param invariants [Array<Bluebook::Invariant>] see `declare`
+        # @param lifecycle [Bluebook::Lifecycle, nil] see `declare`
+        # @return [Class] this piece's own class, self, once identity and indexes are derived
         def absorb(description:, identified_by:, attributes:, commands:, queries:, entities:, preconditions:, invariants:,
                    lifecycle:)
           @description    = description

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

@@ -4,11 +4,13 @@ require_relative "resolver"
 module Hecks
   module Bluebook
     module Expression
-      # ── AST → JSON — walks the real Evaluator/Resolver AST (the same
-      # objects a live dispatch parses `given`/`ensures`/invariant text
-      # into — see docs/implemented/guides/running-a-runtime.md's "The
-      # expression grammar") and emits plain, JSON-serializable Ruby
-      # Hashes, tagged by `"op"`.
+      # Walks the real Evaluator/Resolver AST (the same objects a live
+      # dispatch parses `given`/`ensures`/invariant text into — see
+      # docs/implemented/guides/running-a-runtime.md's "The expression
+      # grammar") and emits plain, JSON-serializable Ruby Hashes, tagged
+      # by `"op"`.
+      #
+      # ## Why this exists beside `rust/project/expr_emitter.rb`
       #
       # The same two-method walk `rust/project/expr_emitter.rb`'s own
       # `emit_bool`/`emit_resolver` already do, over the same AST — that
@@ -26,8 +28,9 @@ module Hecks
       # exact same relationship `rust/project`'s own `Expr` literals
       # already have to the compiled kernel, one layer further out.
       #
-      # Lives in core `lib/hecks`, not `rust/project/` — `rust/project.rb`
-      # is a separate, downstream toolchain
+      # ## Why it lives in core `lib/hecks`, not `rust/project/`
+      #
+      # `rust/project.rb` is a separate, downstream toolchain
       # (`lib/hecks/projector.rb`'s own header: "a whole separate Ruby
       # program"), never `require`d by core `lib/hecks/bluebook/*.rb`
       # files (confirmed: no core file does). `value_object.rb`'s own
@@ -37,22 +40,24 @@ module Hecks
       # run — so it belongs beside `Evaluator`/`Resolver` themselves, not
       # bolted onto a tool that only sometimes runs.
       #
-      # Complete, not corpus-scoped: every node this grammar admits gets
-      # a real arm, the identical "raise, don't silently drop" discipline
-      # `expr_emitter.rb`'s own `emit_bool`/`emit_resolver` already hold
-      # to — even though, as of this writing, no real corpus value object
-      # invariant exercises `Include`/`Modulo`/`BlockPredicate`/`Find`/
-      # `Array`/`MatchesRegex`/`Presence`/`Assignment`/`Split`/`StartsWith`/
-      # `EndsWith`/`First`/`Last` (only `given`/`ensures` clauses do, elsewhere in
-      # the corpus — a different consumer of this same grammar).
-      # `rust/host/src/expr_json.rs`'s own header names exactly which of
-      # these its interpreter evaluates for real today versus refuses
-      # cleanly — a narrower, deliberate, documented boundary on the
-      # interpreting side, not on this emitting side: an author is free
-      # to write any real expression in a value object's own `invariant`,
-      # and this always emits it faithfully; whether `rust/host` can yet
-      # check it at mint time is that file's own question to answer, not
-      # this one's to pre-empt by refusing to even try.
+      # ## Complete, not corpus-scoped
+      #
+      # Every node this grammar admits gets a real arm, the identical
+      # "raise, don't silently drop" discipline `expr_emitter.rb`'s own
+      # `emit_bool`/`emit_resolver` already hold to — even though, as of
+      # this writing, no real corpus value object invariant exercises
+      # `Include`/`Modulo`/`BlockPredicate`/`Find`/`Array`/`MatchesRegex`/
+      # `Presence`/`Assignment`/`Split`/`StartsWith`/`EndsWith`/`First`/
+      # `Last` (only `given`/`ensures` clauses do, elsewhere in the corpus
+      # — a different consumer of this same grammar). `rust/host/src/
+      # expr_json.rs`'s own header names exactly which of these its
+      # interpreter evaluates for real today versus refuses cleanly — a
+      # narrower, deliberate, documented boundary on the interpreting
+      # side, not on this emitting side: an author is free to write any
+      # real expression in a value object's own `invariant`, and this
+      # always emits it faithfully; whether `rust/host` can yet check it
+      # at mint time is that file's own question to answer, not this
+      # one's to pre-empt by refusing to even try.
       module AstJson
         module_function
 
@@ -74,10 +79,20 @@ module Hecks
         # function of `canonical`: the IR carries both so a reader that
         # only displays keeps the text, and a reader that evaluates never
         # re-parses it.
+        #
+        # @param rule [Bluebook::Given, Bluebook::Invariant] the rule to
+        #   render; `rule.ast` is used when already computed, otherwise
+        #   `rule.canonical` is parsed and emitted fresh
+        # @return [Hash{Symbol => Object}] `:description` (`String`),
+        #   `:canonical` (`String`), and `:ast` (`Hash`, the JSON AST)
         def rule_row(rule)
           { description: rule.description, canonical: rule.canonical, ast: rule.ast || emit_predicate(rule.canonical) }
         end
 
+        # Parses `canonical` and emits its JSON AST in one step.
+        #
+        # @param canonical [String] a canonical predicate source string
+        # @return [Hash] the JSON-shaped boolean AST, tagged by `"op"`
         def emit_predicate(canonical)
           emit_bool(Evaluator.parse(canonical))
         end
@@ -89,6 +104,17 @@ module Hecks
         # engine reading it is a defect in the bluebook, refused at build.
         # Walks the emitted AST, so every rule site (givens, ensures,
         # invariants, preconditions, a policy's where) gets the one check.
+        #
+        # @param ast [Hash] a JSON AST node, as emitted by `emit_predicate`
+        #   or `emit_bool`
+        # @param owner [String] the declaring bluebook's name, for the
+        #   refusal message
+        # @param word [String] the rule's own kind and description
+        #   (such as `"given \"total is positive\""`), for the refusal
+        #   message
+        # @return [Hash] `ast`, unchanged
+        # @raise [Bluebook::DSL::Malformed] if any `matches_regex` node's
+        #   pattern uses a construct `PatternSubset` does not admit
         def refuse_unshared_patterns!(ast, owner:, word:)
           return ast if Hecks::Bluebook::MetaValidator.shadow_parsing? # frozen era text is history
 
@@ -107,6 +133,11 @@ module Hecks
 
         # Every name a rule resolves at its root — the first segment of
         # each `lookup` path, unique, in first-seen order.
+        #
+        # @param ast [Hash] a JSON AST node, as emitted by `emit_predicate`
+        #   or `emit_bool`
+        # @return [Array<String>] each `lookup` node's root name, unique,
+        #   in first-seen order
         def lookup_heads(ast)
           heads = []
           each_node(ast) do |node|
@@ -115,6 +146,13 @@ module Hecks
           heads.uniq
         end
 
+        # Visits `node` and every Hash node nested inside it, depth-first.
+        #
+        # @param node [Hash, Array, Object] a JSON AST node, or an Array or
+        #   scalar value found while walking one; a scalar is a silent no-op
+        # @yieldparam node [Hash] each Hash node reached, including `node`
+        #   itself
+        # @return [void]
         def each_node(node, &block)
           case node
           when ::Hash
@@ -125,6 +163,17 @@ module Hecks
           end
         end
 
+        # Emits the JSON form of one boolean-position Evaluator node.
+        #
+        # @param node [Bluebook::Expression::Evaluator::Or,
+        #   Bluebook::Expression::Evaluator::And,
+        #   Bluebook::Expression::Evaluator::Not,
+        #   Bluebook::Expression::Evaluator::Compare,
+        #   Bluebook::Expression::Evaluator::Include,
+        #   Bluebook::Expression::Evaluator::Resolve] the boolean-position
+        #   AST node to emit
+        # @return [Hash] the JSON AST for `node`, tagged by `"op"`
+        # @raise [RuntimeError] if `node` is not one of the handled classes
         def emit_bool(node)
           case node
           when Evaluator::Or  then { "op" => "or", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
@@ -143,6 +192,12 @@ module Hecks
           end
         end
 
+        # Emits the JSON form of one comparison operator.
+        #
+        # @param comparator [Bluebook::Expression::Evaluator::Operator] the
+        #   operator to emit
+        # @return [Hash{String => Boolean}] `"less_than"`, `"equal"`, and
+        #   `"negated"`, exactly as `comparator` carries them
         def emit_comparison(comparator)
           { "less_than" => comparator.compares_less_than, "equal" => comparator.compares_equal, "negated" => comparator.negated }
         end
@@ -158,6 +213,16 @@ module Hecks
         EQ = Evaluator::OPERATORS.find { |op| op.symbol == "==" }
         private_constant :EQ
 
+        # Emits the JSON form of one `include` node.
+        #
+        # @param node [Bluebook::Expression::Evaluator::Include] the
+        #   `include` node to emit
+        # @return [Hash] the JSON AST: `{"op" => "include", ...}` for a
+        #   non-literal haystack, `{"op" => "bool", "value" => false}` for
+        #   an empty literal array haystack, or an `"or"`-of-`"compare"`
+        #   tree of equalities for a non-empty literal array haystack
+        # @raise [RuntimeError] if `node.haystack`, `node.needle`, or one of
+        #   the haystack's literal elements is an unhandled resolver node
         def emit_include(node)
           return { "op" => "include", "haystack" => emit_resolver(node.haystack), "needle" => emit_resolver(node.needle) } \
             unless node.haystack.is_a?(Resolver::ArrayLiteral)
@@ -176,6 +241,33 @@ module Hecks
         # ("every node this grammar admits gets a real arm"); splitting it
         # into several methods would hide whether the set is still
         # exhaustive instead of making that visible at a glance.
+        #
+        # @param node [Bluebook::Expression::Resolver::IntegerLiteral,
+        #   Bluebook::Expression::Resolver::FloatLiteral,
+        #   Bluebook::Expression::Resolver::StringLiteral,
+        #   Bluebook::Expression::Resolver::BoolLiteral,
+        #   Bluebook::Expression::Resolver::NilLiteral,
+        #   Bluebook::Expression::Resolver::Lookup,
+        #   Bluebook::Expression::Resolver::Addition,
+        #   Bluebook::Expression::Resolver::SignTest,
+        #   Bluebook::Expression::Resolver::Empty,
+        #   Bluebook::Expression::Resolver::ToS,
+        #   Bluebook::Expression::Resolver::Modulo,
+        #   Bluebook::Expression::Resolver::Size,
+        #   Bluebook::Expression::Resolver::BlockPredicate,
+        #   Bluebook::Expression::Resolver::Find,
+        #   Bluebook::Expression::Resolver::ArrayLiteral,
+        #   Bluebook::Expression::Resolver::MatchesRegex,
+        #   Bluebook::Expression::Resolver::Presence,
+        #   Bluebook::Expression::Resolver::Assignment,
+        #   Bluebook::Expression::Resolver::Split,
+        #   Bluebook::Expression::Resolver::StartsWith,
+        #   Bluebook::Expression::Resolver::EndsWith,
+        #   Bluebook::Expression::Resolver::First,
+        #   Bluebook::Expression::Resolver::Last] the value-position AST
+        #   node to emit
+        # @return [Hash] the JSON AST for `node`, tagged by `"op"`
+        # @raise [RuntimeError] if `node` is not one of the handled classes
         # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         def emit_resolver(node)
           case node

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

@@ -26,8 +26,19 @@ module Hecks
       module AstReader
         module_function
 
+        # Reads a whole predicate's own `"op"`-tagged JSON back into its AST.
+        #
+        # @param json [Hash{String => Object}] the `"op"`-tagged JSON a rule row's own
+        #   `ast` carries
+        # @return [Evaluator::Or, Evaluator::And, Evaluator::Not, Evaluator::Compare,
+        #   Evaluator::Include, Evaluator::Resolve] the boolean/comparison AST node
         def read_predicate(json) = read_bool(json)
 
+        # Reads one boolean/comparison node, recursing into its own children.
+        #
+        # @param json [Hash{String => Object}] the `"op"`-tagged JSON for one node
+        # @return [Evaluator::Or, Evaluator::And, Evaluator::Not, Evaluator::Compare,
+        #   Evaluator::Include, Evaluator::Resolve] the boolean/comparison AST node
         def read_bool(json)
           case json.fetch("op")
           when "or"      then Evaluator::Or.new(left: read_bool(json["left"]), right: read_bool(json["right"]))
@@ -46,6 +57,10 @@ module Hecks
         # `Operator` carrying that exact triple is the one `parse` would
         # have chosen, because the roster (`expression/projection.json`)
         # holds one symbol per triple.
+        #
+        # @param cmp [Hash{String => Boolean}] `{"less_than"=>, "equal"=>, "negated"=>}`
+        # @return [Evaluator::Operator] the operator carrying that exact triple
+        # @raise [RuntimeError] if no operator in `Evaluator::OPERATORS` has that triple
         def operator(cmp)
           Evaluator::OPERATORS.find do |op|
             op.compares_less_than == cmp.fetch("less_than") &&
@@ -54,6 +69,15 @@ module Hecks
           end or raise "no comparison operator has the triple #{cmp.inspect}"
         end
 
+        # Reads one dotted/arithmetic leaf node, recursing into its own children.
+        #
+        # @param json [Hash{String => Object}] the `"op"`-tagged JSON for one leaf node
+        # @return [Object] a `Resolver` AST node — one of `IntegerLiteral`, `FloatLiteral`,
+        #   `StringLiteral`, `BoolLiteral`, `NilLiteral`, `ArrayLiteral`, `Lookup`,
+        #   `Addition`, `SignTest`, `Empty`, `ToS`, `Modulo`, `Size`, `First`, `Last`,
+        #   `BlockPredicate`, `Find`, `MatchesRegex`, `Presence`, `Assignment`, `Split`,
+        #   `StartsWith`, or `EndsWith`
+        # @raise [RuntimeError] if `json["op"]` names no known resolver op
         # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity -- one arm
         # per AstJson op is the point; splitting the case would hide the roster.
         def read_resolver(json)
@@ -98,6 +122,11 @@ module Hecks
         # triple is what evaluates. Recover the spelling from the
         # vocabulary so a rebuilt node refuses with the same message the
         # parsed one would.
+        #
+        # @param operator [Evaluator::Operator] the comparison operator a sign test's own
+        #   triple resolved to
+        # @return [String] the sign test's own vocabulary name, or `operator.symbol` when
+        #   no sign test shares its triple
         def sign_test_name(operator)
           Resolver::SIGN_TEST_OPERATORS.key(operator.symbol) || operator.symbol
         end

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

@@ -26,6 +26,13 @@ module Hecks
 
         module_function
 
+        # Returns the admitted normalisation rules as plain Hashes, for
+        # embedding in a bluebook's read-back contract.
+        #
+        # @return [Array<Hash{Symbol => String}>] one hash per rule, in
+        #   declared `position` order, with keys `:strategy`,
+        #   `:source_token`, `:replacement`, `:boundary`, and `:position`
+        #   (stringified)
         def table
           RULES.sort_by(&:position).map do |rule|
             {
@@ -38,10 +45,25 @@ module Hecks
           end
         end
 
+        # Rewrites `source` into its canonical spelling by applying every
+        # admitted `RULES` entry, in declared `position` order.
+        #
+        # @param source [String] the raw predicate source to normalise
+        # @return [String] the canonicalised text, stripped of leading and
+        #   trailing whitespace
         def apply(source)
           RULES.sort_by(&:position).reduce(source.to_s) { |text, rule| step(text, rule) }.strip
         end
 
+        # Applies one normalisation `rule` to `text`, dispatching on the
+        # rule's strategy.
+        #
+        # @param text [String] the source text (or string-literal segment) to
+        #   transform
+        # @param rule [Rule] the normalisation rule to apply
+        # @return [String] `text` after the rule is applied
+        # @raise [ArgumentError] if `rule.strategy` names a strategy this
+        #   method does not implement
         def step(text, rule)
           case rule.strategy
           when "collapse_whitespace" then map_outside_strings(text) { |segment| segment.gsub(/\s+/, " ") }
@@ -51,6 +73,14 @@ module Hecks
           end
         end
 
+        # Substitutes every occurrence of `rule.source_token` in `text` with
+        # `rule.replacement`, honoring the rule's word-boundary setting.
+        #
+        # @param text [String] the source text (or string-literal segment) to
+        #   transform
+        # @param rule [Rule] the `"replace"`-strategy rule supplying the
+        #   token, replacement, and boundary
+        # @return [String] `text` with the substitution applied
         def replace(text, rule)
           map_outside_strings(text) do |segment|
             if rule.boundary == "none"
@@ -61,21 +91,30 @@ module Hecks
           end
         end
 
-        # Applies a normalisation rule to the text outside quoted string
-        # literals only, copying every quoted run through byte-for-byte.
-        # Every rule here (collapse_whitespace, the `.length`→`.size` fold)
-        # used to run quote-blind — `"a  b"` collapsed to `"a b"` and
-        # `"a.length"` folded to `"a.size"` just as readily as the real
-        # source outside the quotes, silently rewriting what a predicate
-        # compares a string attribute against, not merely how the
-        # predicate itself is spelled. A canonical string literal's
-        # contents are data, never syntax to normalise.
+        # Applies the given block to the text outside quoted string literals
+        # only, copying every quoted run through byte-for-byte. Every rule
+        # here (collapse_whitespace, the `.length`→`.size` fold) must stay
+        # quote-aware: run it quote-blind and `"a  b"` collapses to `"a b"`,
+        # `"a.length"` folds to `"a.size"`, just as readily as the real
+        # source outside the quotes — silently rewriting what a predicate
+        # compares a string attribute against, not merely how the predicate
+        # itself is spelled. A canonical string literal's contents are data,
+        # never syntax to normalise.
         #
         # Handles both `"` and `'` delimiters (this grammar's own
         # `Resolver.quoted?` admits either), quote-aware exactly the way
         # `Evaluator.top_level_index`/`Resolver.array_elements` already are
         # elsewhere in this sublanguage. An unterminated quote (malformed
         # input) is passed through raw rather than risk mangling it further.
+        #
+        # @param text [String] the source text to scan for quoted string
+        #   literals
+        # @yieldparam segment [String] a run of `text` outside any quoted
+        #   literal
+        # @yieldreturn [String] the transformed replacement for `segment`
+        # @return [String] `text` with the block applied to every unquoted
+        #   run, and every quoted run (`"`- or `'`-delimited) copied through
+        #   unchanged
         def map_outside_strings(text)
           result = +""
           buffer = +""