hecks 1.3.0 → 1.4.0

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

@@ -8,6 +8,7 @@ module Hecks
       # vocabulary of its own; `WorldBuilder#record_binding` reads `#to_h`
       # back out.
       class SettingsCollector
+        # Starts with no settings recorded.
         def initialize = @values = {}
 
         def method_missing(key, *args, &)
@@ -19,9 +20,9 @@ module Hecks
         def to_h = @values
       end
 
-      # THE AGGREGATE-QUALIFIED MIRROR (#143) — a `.world` file's own
+      # The aggregate-qualified mirror (#143) — a `.world` file's own
       # `Pizzas::Order.charged_by("Stripe") do ... end` visually mirrors the
-      # SAME bind line the sibling `.hecksagon` file already writes
+      # same bind line the sibling `.hecksagon` file already writes
       # (`HecksagonBuilder`'s own `BindingProxy`), but `IR::World#for_verb`/
       # `#for_binding` key purely by verb and adapter name — the aggregate
       # qualifier is never read back out, it exists only for that visual
@@ -30,12 +31,19 @@ module Hecks
       # not, has to land in the exact same `@settings` write path
       # (`WorldBuilder#record_binding`).
       class WorldConstProxy
+        # Mints the stand-in module a bare domain constant resolves to inside a `.world` block.
+        #
+        # @param builder [Bluebook::DSL::WorldBuilder] the builder every verb called through the
+        #   module's proxies records its settings on
+        # @return [Module] an anonymous module whose `const_missing` answers a `WorldConstProxy`,
+        #   whatever aggregate name follows `::`
         def self.namespace(builder)
           Module.new do
             define_singleton_method(:const_missing) { |_aggregate| WorldConstProxy.new(builder) }
           end
         end
 
+        # @param builder [Bluebook::DSL::WorldBuilder] the builder verb calls are recorded on
         def initialize(builder) = @builder = builder
 
         def method_missing(verb, *args, **kwargs, &block) = @builder.record_binding(verb, args, kwargs, block)
@@ -45,7 +53,7 @@ module Hecks
 
       # Parses a `.world` file's top-level DSL block into a `World` — a
       # domain's own `realm`/`latest` version markers plus its adapter bind
-      # SETTINGS, one entry per `verb("Adapter") do ... end` call (whether
+      # settings, one entry per `verb("Adapter") do ... end` call (whether
       # written bare or aggregate-qualified through `WorldConstProxy`'s
       # visual mirror of a sibling `.hecksagon` file's own bind).
       class WorldBuilder
@@ -53,23 +61,37 @@ module Hecks
 
         include WordGate
 
+        # @param domain [String] name of the domain whose world this is
         def initialize(domain)
           @domain   = domain
           @settings = {}
         end
 
-        # RENAMED FROM `realm`/`latest` — item #13's full metaprogrammed
-        # dispatch (slice 5). Neither bootstrap-reachable (checked
-        # directly). Reached through `WordGate#method_missing`'s new
+        # Names the realm this world belongs to, such as `"Examples"` or `"QA"`.
+        #
+        # `realm_impl`/`latest_impl` answer the `realm`/`latest` words
+        # through the table's `calls:` column — item #13's full
+        # metaprogrammed dispatch (slice 5). Neither bootstrap-reachable
+        # (checked directly). Reached through `WordGate`'s
         # `word_gate_dispatch`, called explicitly below since
         # `WorldBuilder`'s own class-level `method_missing` (the
         # open-verb catch-all beneath this) always wins over the
         # module's — see `word_gate.rb`'s own header for the full
         # mechanism.
+        #
+        # @param value [String, Symbol] the realm's name; blankness is judged by the world
+        #   language at `build`, not here
+        # @return [String] the realm as stored
         def realm_impl(value)
           @realm = required(value, "realm")
         end
 
+        # Names the bluebook version this world treats as latest, which `ProjectRegister` compares
+        # with the bluebook's own declared `version`.
+        #
+        # @param value [String, Symbol, Numeric] the version marker; blankness is judged by the
+        #   world language at `build`, not here
+        # @return [String] the version as stored
         def latest_impl(value)
           @latest = required(value, "latest version")
         end
@@ -83,11 +105,20 @@ module Hecks
 
         def respond_to_missing?(_name, _include_private = false) = true
 
-        # EXTRACTED from the old `method_missing` body (#143) so
+        # Records one bind's settings under both its verb and its `verb:adapter` key.
+        #
+        # A method of its own, apart from `method_missing` (#143), so
         # `WorldConstProxy`'s own aggregate-qualified verb calls
         # (`Pizzas::Order.charged_by(...)`) write into the exact same
         # place the bare top-level spelling (`charged_by(...)`) already
         # does — one write path, two spellings.
+        #
+        # @param verb [Symbol, String] the bind verb, such as `:persisted_by`
+        # @param args [Array<Object>] the call's positional arguments; the first names the adapter
+        # @param kwargs [Hash{Symbol => Object}] settings given inline as keyword arguments
+        # @param block [Proc, nil] a settings block, evaluated against a `SettingsCollector`
+        # @return [Hash{Symbol => Object}] the settings just recorded: `:adapter` (a String),
+        #   then the keyword arguments, then the block's settings, later ones winning
         def record_binding(verb, args, kwargs, block)
           collector = SettingsCollector.new
           collector.instance_eval(&block) if block
@@ -96,18 +127,30 @@ module Hecks
           @settings["#{verb}:#{args.first.to_s.downcase}"] = value
         end
 
+        # Assembles the realm, version marker and bind settings, judged by the world language.
+        #
+        # @return [Bluebook::World] the world, returned once the language accepts it
+        # @raise [Bluebook::DSL::Malformed] if the world language refuses the declaration, such
+        #   as a blank `realm`
         def build
           MetaValidator.call_world(
             World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings)
           )
         end
 
+        # Evaluates a `Hecks.world` block against a fresh builder and returns the world it declared.
+        #
         # `ConstShim`'s resolver, the same bridge `HecksagonBuilder`/
         # `BluebookBuilder` already wrap their own `instance_eval` in
-        # (#143) — without it, `Pizzas::Order.charged_by(...)` raised
+        # (#143) — without it, `Pizzas::Order.charged_by(...)` raises
         # `NameError: uninitialized constant Pizzas` for every `.world`
         # file using the aggregate-qualified mirror form, since a bare
         # `Pizzas` has no real constant to resolve to.
+        #
+        # @param domain [String] name of the domain whose world this is
+        # @yield the world body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::World] the judged world
+        # @raise [Bluebook::DSL::Malformed] if the world language refuses the declaration
         def self.build(domain, &block)
           builder  = new(domain)
           resolver = ->(_domain) { WorldConstProxy.namespace(builder) }

data/lib/hecks/bluebook/entity.rb

@@ -3,10 +3,10 @@ require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
-    # An entity, as a RUBY CLASS — a piece of an aggregate that has an identity
+    # An entity, as a Ruby class — a piece of an aggregate that has an identity
     # of its own.
     #
-    # Crossing over closes the OWNER CHAIN. An entity declares commands, and
+    # Crossing over closes the owner chain. An entity declares commands, and
     # until now those commands had no owner that could state an identity: an
     # entity was an IR object, not a construct, so `Construct#hecks_fqn` refused
     # rather than answering "Deposit" and looking right. Four of banking's
@@ -14,15 +14,15 @@ module Hecks
     # `Banking::Account.Ledger.Deposit` — which is the id the judge already mints
     # for them.
     #
-    # NOT const_set, for the same reason a command is not: a name inside one
+    # Not const_set, for the same reason a command is not: a name inside one
     # aggregate can denote more than one kind of thing, so the constant tree
     # cannot index it.
     #
-    # It must stay STRUCTURALLY INTERCHANGEABLE with an aggregate — the runtime
+    # It must stay structurally interchangeable with an aggregate — the runtime
     # builds `Instance.new(aggregate: entity)` and `CommandRules` takes either as
     # `declaring` — so it answers `hecks_name`, `attributes`, `attribute`,
     # `identified_by` and `lifecycle` exactly as an aggregate does. And it must
-    # keep NOT answering `value_object`: `Value.for_attribute` sniffs for that
+    # keep not answering `value_object`: `Value.for_attribute` sniffs for that
     # method to tell a piece from a head.
     class Entity
       extend Construct
@@ -39,26 +39,26 @@ module Hecks
         # S17, ADR 0026 — "That is what `entity` is for, and `entity` is
         # declared by the language and used zero times in it" (the ADR's
         # own words). Dispatch nests inside Handler, so an entity's own
-        # NESTED entities are part of its wire shape now, the same way
+        # nested entities are part of its wire shape now, the same way
         # an aggregate's always were — the field the ADR names as
         # declared-but-unused until this slice.
         entities:      many(:entities),
-        # ADR 0028 — a piece's own `given`, the SAME shape
+        # ADR 0028 — a piece's own `given`, the same shape
         # `Aggregate#preconditions` already carries (its own `emits_ir`
         # row, identical). A precondition shared across this piece's own
         # commands, declared once — a command references it back by
-        # name; the resolved text still lands on EACH referencing
+        # name; the resolved text still lands on each referencing
         # command's own `givens` either way, so this field is read-only
         # documentation of what the piece itself declared, the same
         # relationship `Aggregate.preconditions` already has to its own
         # commands.
         preconditions: -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
-        # A piece's OWN shape rule, checked against EVERY instance of
+        # A piece's own shape rule, checked against every instance of
         # this piece the aggregate holds (Admissibility#enforce_
-        # invariants' own recursive walk) — the SAME relationship
+        # invariants' own recursive walk) — the same relationship
         # `ValueObject#invariants` already has to its own instances,
         # one level up the construct tree. Not a separate enforcement
-        # boundary; still checked at the SAME two points (after every
+        # boundary; still checked at the same two points (after every
         # mutation, before save) the aggregate's own invariants always
         # were — see that method's own comment for why this does not
         # contradict "there is no separate entity invariant."

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

@@ -4,17 +4,17 @@ require_relative "resolver"
 module Hecks
   module Bluebook
     module Expression
-      # ── AST → JSON — walks the REAL Evaluator/Resolver AST (the same
+      # ── 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"`.
       #
-      # THE SAME TWO-METHOD WALK `rust/project/expr_emitter.rb`'s own
-      # `emit_bool`/`emit_resolver` already do, over the SAME AST — that
-      # file's own methods build RUST SOURCE-CODE STRINGS for `rust/
+      # The same two-method walk `rust/project/expr_emitter.rb`'s own
+      # `emit_bool`/`emit_resolver` already do, over the same AST — that
+      # file's own methods build Rust source-code strings for `rust/
       # project`'s codegen (`rust/src/kernel::expr::Expr` literals, baked
-      # into a generated domain's own compiled binary); this builds DATA
+      # into a generated domain's own compiled binary); this builds data
       # instead, for a genuinely different consumer with a genuinely
       # different constraint: `rust/host` can never link the `rust`
       # (kernel) crate at all (a real, load-bearing build constraint —
@@ -22,25 +22,25 @@ module Hecks
       # path dependency would statically bake every domain's generated
       # dispatch code into every Lambda binary), so a value object's own
       # `invariant` predicate has to travel as something `rust/host` can
-      # deserialize and interpret itself, at RUNTIME, from `ir.json` — the
+      # deserialize and interpret itself, at runtime, from `ir.json` — the
       # 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`
+      # 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
-      # `invariants:` IR emission needs this for EVERY domain's ordinary
+      # `invariants:` IR emission needs this for every domain's ordinary
       # `to_h`/`ir.json` export — golden fixtures, `hecks-parse`'s parity
       # comparisons, and any deploy artifact, not only a `bin/project_rust`
       # 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
+      # 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
+      # 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
@@ -48,15 +48,15 @@ module Hecks
       # `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`,
+      # 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
+      # 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
 
-        # THE CLOSED OP ROSTER — every `"op"` tag the walkers below can
+        # **The closed op roster** — every `"op"` tag the walkers below can
         # emit, pinned so a reader (or a spec) can refuse a tag it does
         # not know instead of guessing. A new node kind is a new entry
         # here, a new arm below, and a new arm in every reader.
@@ -68,7 +68,7 @@ module Hecks
           matches_regex presence assignment split starts_with ends_with
         ].freeze
 
-        # ONE RULE ROW, THE WAY EVERY RULE SITE EMITS IT — description and
+        # One rule row, the way every rule site emits it — description and
         # canonical text (what every reader has always had) plus the
         # structured form, derived from the same text. `ast` is a pure
         # function of `canonical`: the IR carries both so a reader that
@@ -149,9 +149,9 @@ module Hecks
 
         # The JSON-target sibling of `expr_emitter.rb`'s own
         # `emit_include` — see that method's own comment for the full
-        # reasoning (a LITERAL array haystack has no `Expr::Include`-
-        # representable shape on EITHER target, kernel or host, so both
-        # rewrite it identically into an OR-of-equalities at emission
+        # reasoning (a literal array haystack has no `Expr::Include`-
+        # representable shape on either target, kernel or host, so both
+        # rewrite it identically into an or-of-equalities at emission
         # time rather than carrying a shape neither interpreter could
         # evaluate). A non-literal haystack still emits `include`
         # unchanged.
@@ -172,7 +172,7 @@ module Hecks
         end
 
         # One case arm per Resolver node type — the class header above is
-        # explicit that this dispatch must stay COMPLETE and in one place
+        # explicit that this dispatch must stay complete and in one place
         # ("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.
@@ -184,7 +184,7 @@ module Hecks
           when Resolver::StringLiteral  then { "op" => "str", "value" => node.value }
           when Resolver::BoolLiteral    then { "op" => "bool", "value" => node.value }
           when Resolver::NilLiteral     then { "op" => "nil" }
-          # `path` is the SAME shape `find.path` already has — segments, not
+          # `path` is the same shape `find.path` already has — segments, not
           # a dotted string a reader would have to split by its own rule.
           when Resolver::Lookup         then { "op" => "lookup", "path" => node.path.split(".") }
           when Resolver::Addition       then { "op" => "add", "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }

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

@@ -4,8 +4,8 @@ require_relative "resolver"
 module Hecks
   module Bluebook
     module Expression
-      # THE INVERSE OF `AstJson` — reads the `"op"`-tagged JSON a rule row
-      # carries as `ast` back into the SAME `Evaluator`/`Resolver` node
+      # The inverse of `AstJson` — reads the `"op"`-tagged JSON a rule row
+      # carries as `ast` back into the same `Evaluator`/`Resolver` node
       # Structs `Evaluator.parse` builds from `canonical`. This is how the
       # runtime evaluates a rule without re-parsing its text: the one
       # parse happened at DSL-build time, behind `AstJson`; dispatch walks
@@ -19,7 +19,7 @@ module Hecks
       # the spec proved the round trip first, then the runtime adopted it.
       #
       # One deliberate asymmetry, inherited: `AstJson` rewrites a
-      # LITERAL-array `.include?` into an OR of equalities (see
+      # literal-array `.include?` into an or of equalities (see
       # `emit_include`), so reading never produces an `Include` over an
       # `ArrayLiteral`. Evaluation is unchanged by that rewrite, which is
       # exactly what the equivalence spec pins.

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

@@ -4,7 +4,7 @@ require_relative "../../vocabulary"
 module Hecks
   module Bluebook
     module Expression
-      # Rewrites a predicate's SOURCE TEXT into one canonical spelling
+      # Rewrites a predicate's source text into one canonical spelling
       # before it's ever parsed or hashed — collapsing whitespace and
       # folding admitted synonyms (e.g. `.length` → `.size`) via the
       # `RULES` table projected from the grammar chapter, so two byte-
@@ -16,7 +16,7 @@ module Hecks
 
         STRATEGIES = Hecks::Vocabulary.fetch("NormalisationStrategy")
 
-        # READ, NOT RESTATED — the admitted normalisation rules, projected
+        # **Read, not restated** — the admitted normalisation rules, projected
         # from the grammar chapter by bin/expression_projection exactly as
         # the evaluator's operator table is. See Evaluator::PROJECTION for
         # why a projection rather than a boot.
@@ -61,7 +61,7 @@ module Hecks
           end
         end
 
-        # Applies a normalisation rule to the text OUTSIDE quoted string
+        # 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
@@ -69,7 +69,7 @@ module Hecks
         # 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.
+        # contents are data, never syntax to normalise.
         #
         # Handles both `"` and `'` delimiters (this grammar's own
         # `Resolver.quoted?` admits either), quote-aware exactly the way
@@ -93,9 +93,9 @@ module Hecks
               result << yield(buffer)
               # `char.dup`, not `char.to_s` (a no-op on a String — always
               # returns self, never a copy) and not `+char` either
-              # (`String#+@` only dups a FROZEN receiver; `each_char`'s
+              # (`String#+@` only dups a frozen receiver; `each_char`'s
               # yielded strings aren't frozen, so `+char` is just as
-              # much a no-op here). Without a REAL copy, `buffer` and
+              # much a no-op here). Without a real copy, `buffer` and
               # `quote` alias the same mutable object: the very next
               # `buffer << char` grows `quote` right along with it, so
               # `char == quote` can only ever compare a single character
@@ -103,12 +103,12 @@ module Hecks
               # literal — everything after a predicate's first quoted
               # string silently skipped normalisation for the rest of
               # the text, undetected because passing text through
-              # unnormalised is silent. MASKED by every existing spec
-              # here, which only checks that quoted CONTENTS survive
+              # unnormalised is silent. Masked by every existing spec
+              # here, which only checks that quoted contents survive
               # untouched (the M7 fix this method exists for) — that
               # still holds by accident once the bug makes the "outside"
               # branch unreachable. Found live: a multi-line `given`/
-              # `ensures` block whose ONLY quoted literal closes before a
+              # `ensures` block whose only quoted literal closes before a
               # later line — the newline and that later line's own
               # indentation went uncollapsed, diverging from
               # `hecks-parse`'s own (correct) single-space join.

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
@@ -65,8 +65,8 @@ module Hecks
           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
@@ -87,18 +87,18 @@ module Hecks
           rule.ast ? AstReader.read_predicate(rule.ast) : parse(rule.canonical)
         end
 
-        # A refused `given`/`ensures`/`invariant` names its own DESCRIPTION
+        # 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` —
+        # 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
+        # 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.
@@ -122,8 +122,8 @@ 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
@@ -181,7 +181,7 @@ 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.
         def apply(comparator, lhs, rhs)
           result = (comparator.compares_less_than && less_than(lhs, rhs)) ||
@@ -215,13 +215,13 @@ module Hecks
           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
@@ -311,13 +311,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,7 +329,7 @@ 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
@@ -337,7 +337,7 @@ module Hecks
             # 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
+            # this expression's own boolean/comparison grammar, exactly
             # the way an un-tracked `{`/`}` once did for block predicates.
             elsif ["(", "{", "["].include?(char)
               depth += 1

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
@@ -210,7 +210,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