hecks 2.8.0 → 3.0.0

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

@@ -4,67 +4,14 @@ require_relative "resolver"
 module Hecks
   module Bluebook
     module Expression
-      # 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
-      # 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
-      # 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 —
-      # `reference_validate.rs`'s own header has the full reasoning: one
-      # 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
-      # exact same relationship `rust/project`'s own `Expr` literals
-      # already have to the compiled kernel, one layer further out.
-      #
-      # ## 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
-      # `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 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.
+      # Walks the Evaluator/Resolver AST and emits JSON-serializable Hashes tagged by `"op"`.
+      # Lives in core because rust/host cannot link the kernel crate and interprets this from
+      # ir.json.
       module AstJson
         module_function
 
-        # **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.
+        # The closed roster of `"op"` tags. A new node kind needs an entry here and an arm in
+        # each walker and reader; unhandled nodes raise rather than being dropped.
         OPS = %w[
           or and not compare include
           int float str bool nil array lookup
@@ -73,48 +20,20 @@ module Hecks
           matches_regex presence assignment split starts_with ends_with
         ].freeze
 
-        # 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
-        # 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)
+        # One rule row: description, canonical text, and the AST derived from that text.
         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
 
-        # C3.6 (docs/semantics/bluebook-semantics.md) — every `.match?`
-        # pattern a rule carries is held to `PatternSubset`, exactly as an
-        # attribute's own `pattern:` already is (`AttributeCollector#
-        # refuse_unshared_pattern`): a regex whose meaning depends on the
-        # 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.
+        # Holds every `.match?` pattern a rule carries to `PatternSubset`, as an attribute's
+        # `pattern:` is; walking the AST gives every rule site 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
+        # @raise [Bluebook::DSL::Malformed] if a `matches_regex` pattern is outside `PatternSubset`
         def refuse_unshared_patterns!(ast, owner:, word:)
           return ast if Hecks::Bluebook::MetaValidator.shadow_parsing? # frozen era text is history
 
@@ -132,30 +51,18 @@ module Hecks
         end
 
         # What a `lookup` path can never contain: a call's parentheses, or an argument list's
-        # commas and spaces. Attribute names carry none of these, so a path that does is a method
-        # call with arguments that the grammar has no node for.
+        # commas and spaces.
         #
-        # A bare `?` is deliberately not in the set. `x.nil?` also parses as a lookup, but it loads
-        # and, on a String, Boolean or `nil` value, evaluates without raising; real bluebooks
-        # declare it, so refusing it would stop them loading.
+        # A bare `?` is deliberately not in the set: `x.nil?` also parses as a lookup, loads, and
+        # evaluates without raising, and real bluebooks declare it.
         UNRESOLVABLE_PATH = /[(),\s]/
         private_constant :UNRESOLVABLE_PATH
 
-        # Refuses a rule that calls a method the expression grammar does not have.
-        #
-        # An unrecognised call such as `value.between?(100, 599)` parses as a `lookup` whose path
-        # names an attribute that can never exist, so it loads and then fails on the first
-        # dispatch. Refusing it here moves the failure to build time, where the author is looking.
-        # The supported spellings (comparisons joined with `&&`/`||`, `.positive?`, `.empty?`,
-        # `.include?`, ...) are the rows of `projection.json`.
+        # Refuses a rule that calls a method the grammar lacks, such as `value.between?(100, 599)`.
+        # It would parse as a `lookup` of an attribute that cannot exist and fail on first dispatch.
         #
-        # @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
-        #   `"invariant \"a status code\""`), for the refusal message
-        # @return [Hash] `ast`, unchanged
-        # @raise [Bluebook::DSL::Malformed] if any `lookup` node's path contains a parenthesis,
-        #   comma or whitespace
+        # @raise [Bluebook::DSL::Malformed] if a `lookup` path contains a parenthesis, comma or
+        #   space
         def refuse_unresolvable_lookups!(ast, owner:, word:)
           return ast if Hecks::Bluebook::MetaValidator.shadow_parsing? # frozen era text is history
 
@@ -174,13 +81,7 @@ module Hecks
           ast
         end
 
-        # 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
+        # Every name a rule resolves at its root: the first segment of each `lookup` path, unique.
         def lookup_heads(ast)
           heads = []
           each_node(ast) do |node|
@@ -189,13 +90,7 @@ 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]
+        # Visits `node` and every Hash nested inside it, depth-first.
         def each_node(node, &block)
           case node
           when ::Hash
@@ -207,16 +102,6 @@ module Hecks
         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) }
@@ -236,36 +121,16 @@ module Hecks
         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
 
-        # 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
-        # time rather than carrying a shape neither interpreter could
-        # evaluate). A non-literal haystack still emits `include`
-        # unchanged.
+        # Mirrors `expr_emitter.rb`'s `emit_include`: no target can represent a literal-array
+        # haystack in `include`, so it is rewritten to an or of equalities at emission.
         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
+        # Emits one `include` node; an empty literal haystack is `false`.
         def emit_include(node)
           return { "op" => "include", "haystack" => emit_resolver(node.haystack), "needle" => emit_resolver(node.needle) } \
             unless node.haystack.is_a?(Resolver::ArrayLiteral)
@@ -279,38 +144,8 @@ module Hecks
           equalities.reduce { |left, right| { "op" => "or", "left" => left, "right" => right } }
         end
 
-        # One case arm per Resolver node type — the class header above is
-        # 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.
-        #
-        # @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
+        # One case arm per Resolver node type, kept in one method so exhaustiveness shows at a
+        # glance.
         # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         def emit_resolver(node)
           case node
@@ -319,8 +154,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
-          # a dotted string a reader would have to split by its own rule.
+          # Segments, as `find.path` has, so a reader need not split a dotted string.
           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) }
           when Resolver::SignTest

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

@@ -4,41 +4,20 @@ 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
-      # 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
-      # the structured form (`Evaluator.call_rule`), and `canonical` stays
-      # what it always displayed as — text for humans and refusal wording.
-      #
-      # Written as the obvious mirror of `ast_json.rb`'s two walkers, arm
-      # for arm, so a new op there is a new arm here and
-      # spec/expression_ast_spec.rb's roster contract fails until it
-      # lands. Promoted from spec/support once the runtime switched —
-      # 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
-      # `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.
+      # The inverse of `AstJson`: reads a rule row's `"op"`-tagged `ast` back into the
+      # `Evaluator`/`Resolver` nodes, so dispatch evaluates a rule without re-parsing its text.
       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
+        # Arm for arm with `AstJson`: a new op there fails spec/expression_ast_spec.rb until added
+        # here.
+        # A literal-array `.include?` is emitted as an or of equalities, so it never reads back as
+        # an `Include` over an `ArrayLiteral`; evaluation is unchanged.
+
+        # Reads a whole predicate's `"op"`-tagged JSON back into its AST.
         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"]))
@@ -53,14 +32,8 @@ module Hecks
           end
         end
 
-        # The comparator algebra travels as its three-flag triple; the
-        # `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
+        # The roster (`expression/projection.json`) holds one symbol per flag triple,
+        # so the triple identifies the operator `parse` would have chosen.
         def operator(cmp)
           Evaluator::OPERATORS.find do |op|
             op.compares_less_than == cmp.fetch("less_than") &&
@@ -70,14 +43,6 @@ module Hecks
         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)
@@ -118,15 +83,8 @@ module Hecks
         end
         # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
-        # `SignTest#test` is only wording (the refusal names it); the
-        # 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
+        # `SignTest#test` is only refusal wording; recovering it keeps a rebuilt node's message
+        # identical to the parsed one's.
         def sign_test_name(operator)
           Resolver::SIGN_TEST_OPERATORS.key(operator.symbol) || operator.symbol
         end

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

@@ -4,35 +4,21 @@ require_relative "../../vocabulary"
 module Hecks
   module Bluebook
     module Expression
-      # 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-
-      # different but equivalent predicates compare and cache identically.
-      # Never touches text inside quoted string literals
-      # (`map_outside_strings`).
+      # Rewrites predicate source into one canonical spelling (whitespace, admitted synonyms)
+      # so equivalent predicates compare and hash alike. Quoted string literals are left alone.
       module CanonicalForm
         Rule = Struct.new(:strategy, :source_token, :replacement, :boundary, :position, keyword_init: true)
 
         STRATEGIES = Hecks::Vocabulary.fetch("NormalisationStrategy")
 
-        # **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.
+        # Normalisation rules projected from the grammar chapter by hecks project_expression_tables.
         RULES = JSON.parse(
           File.read(File.join(__dir__, "projection.json")), symbolize_names: true
         ).fetch(:normalisations).map { |row| Rule.new(**row) }.freeze
 
         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)
+        # The normalisation rules as plain Hashes, in `position` order, for a read-back contract.
         def table
           RULES.sort_by(&:position).map do |rule|
             {
@@ -45,25 +31,11 @@ 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
+        # Applies every `RULES` entry to `source` in `position` order; returns the stripped result.
         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+/, " ") }
@@ -73,14 +45,6 @@ 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"
@@ -91,30 +55,9 @@ module Hecks
           end
         end
 
-        # 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
+        # Yields each run of `text` outside quoted literals, copying quoted runs through verbatim.
+        # Quote-blind rewriting would change what a predicate compares a string against.
+        # Handles `"` and `'`; an unterminated quote is passed through raw.
         def map_outside_strings(text)
           result = +""
           buffer = +""
@@ -130,29 +73,9 @@ module Hecks
               end
             elsif ['"', "'"].include?(char)
               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
-              # yielded strings aren't frozen, so `+char` is just as
-              # 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
-              # against an ever-lengthening string and never closes the
-              # 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
-              # 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
-              # later line — the newline and that later line's own
-              # indentation went uncollapsed, diverging from
-              # `hecks-parse`'s own (correct) single-space join.
-              # `spec/parser_parity_spec.rb`, roster's "a front-row seat
-              # takes a member of age".
+              # Must be a real copy: aliasing `buffer` and `quote` makes `buffer << char` grow
+              # `quote`, so the literal never closes and later text skips normalisation.
+              # Pinned by spec/parser_parity_spec.rb (multi-line `given`/`ensures`).
               buffer = char.dup
               quote = char.dup
             else