hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,261 @@
+require "json"
+require_relative "../../vocabulary"
+
+module Hecks
+  module Bluebook
+    module Expression
+      module Evaluator
+        Operator = Struct.new(:symbol, :compares_less_than, :compares_equal, :negated, keyword_init: true)
+
+        # 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.
+        #
+        # 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
+        # every predicate through CanonicalForm while a bluebook loads — so
+        # the projection is how the domain reaches here: regenerated when the
+        # ledger changes, held fresh by spec/operators_export_spec.rb, and
+        # held to the live machinery by spec/operator_conformance_spec.rb.
+        PROJECTION = JSON.parse(
+          File.read(File.join(__dir__, "projection.json")), symbolize_names: true
+        ).freeze
+
+        OPERATORS = PROJECTION.fetch(:operators)
+                              .select { |row| row[:category] == "comparison" }
+                              .map { |row| Operator.new(**row.slice(:symbol, :compares_less_than, :compares_equal, :negated)) }
+                              .freeze
+
+        COMPARISONS = OPERATORS.map(&:symbol).freeze
+
+        # The boolean/comparison grammar an expression parses into. Leaf nodes
+        # (Compare/Include/Resolve) hold already-parsed Resolver ASTs, not raw
+        # strings — which branch a leaf's grammar takes is, like the boolean/
+        # comparison grammar above it, a pure function of the string. Only the
+        # final state/attrs dictionary read, inside Resolver.interpret, varies
+        # per call. Parsing the whole tree once and caching it (ast_cache,
+        # below) is what makes that safe.
+        Or      = Struct.new(:left, :right, keyword_init: true)
+        And     = Struct.new(:left, :right, keyword_init: true)
+        Not     = Struct.new(:node, keyword_init: true)
+        Compare = Struct.new(:operator, :left, :right, keyword_init: true)
+        Include = Struct.new(:haystack, :needle, keyword_init: true)
+        Resolve = Struct.new(:expr, keyword_init: true)
+
+        module_function
+
+        # Keyed by the exact string `call` receives. Canonical text is already
+        # normalised at DSL-build time, so the same given/invariant's text is
+        # byte-identical across every dispatch that evaluates it — parsed once
+        # here, interpreted fresh against each call's own state/attrs. Matches
+        # MetaValidator.verdicts' unsynchronized `||= {}` idiom : redundant
+        # parse work under real parallelism, never corruption.
+        def ast_cache = @ast_cache ||= {}
+
+        def call(expr, state, attrs = {})
+          interpret(ast_cache[expr] ||= parse(expr), state, attrs)
+        end
+
+        def parse(expr)
+          expr = strip_parens(expr.to_s.strip)
+
+          left, right = split_top_level(expr, "||")
+          return Or.new(left: parse(left), right: parse(right)) if left
+
+          left, right = split_top_level(expr, "&&")
+          return And.new(left: parse(left), right: parse(right)) if left
+
+          membership = match_include(expr)
+          return Include.new(haystack: Resolver.parse(membership[0]), needle: Resolver.parse(membership[1])) if membership
+
+          OPERATORS.each do |op|
+            left, right = split_comparison(expr, op.symbol)
+            return Compare.new(operator: op, left: Resolver.parse(left), right: Resolver.parse(right)) if left
+          end
+
+          return Not.new(node: parse(Regexp.last_match(1))) if expr =~ /\A!(.+)\z/
+
+          Resolve.new(expr: Resolver.parse(expr))
+        end
+
+        def interpret(node, state, attrs)
+          case node
+          when Or      then interpret(node.left, state, attrs) || interpret(node.right, state, attrs)
+          when And     then interpret(node.left, state, attrs) && interpret(node.right, state, attrs)
+          when Not     then !interpret(node.node, state, attrs)
+          when Compare then compare(node.operator, node.left, node.right, state, attrs)
+          when Include then includes?([node.haystack, node.needle], state, attrs)
+          when Resolve then truthy?(Resolver.interpret(node.expr, state, attrs))
+          else
+            # Every node `parse` can produce has a `when` above — a
+            # backstop against the day this grammar grows a new node
+            # type and `interpret` doesn't grow to match it. A missing
+            # arm here used to return bare `nil`, and `Or`/`And` fold
+            # that straight into the boolean algebra as ordinary falsy
+            # — reading exactly like "the rule legitimately does not
+            # hold" rather than "the runtime cannot evaluate this rule
+            # at all", the one silent no-op this language otherwise
+            # refuses.
+            raise EvaluationError, "no interpreter handles #{node.class} — add a case before parse can produce it"
+          end
+        end
+
+        def compare(op, left, right, state, attrs)
+          lhs = Resolver.interpret(left, state, attrs)
+          rhs = Resolver.interpret(right, state, attrs)
+
+          apply(op, lhs, rhs)
+        end
+
+        # 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
+        # re-deriving positive?/negative?/zero? by hand a second time.
+        def apply(op, lhs, rhs)
+          result = (op.compares_less_than && less_than(lhs, rhs)) ||
+                   (op.compares_equal && equal?(lhs, rhs))
+          op.negated ? !result : result
+        end
+
+        def less_than(lhs, rhs)
+          left  = Resolver.numeric(lhs)
+          right = Resolver.numeric(rhs)
+          return left < right if left && right
+          return lhs < rhs    if lhs.is_a?(String) && rhs.is_a?(String)
+
+          raise EvaluationError,
+                "comparison of #{class_of(lhs)} with #{Resolver.describe(rhs)} failed"
+        end
+
+        def equal?(lhs, rhs)
+          left  = Resolver.numeric(lhs)
+          right = Resolver.numeric(rhs)
+          return left == right if left && right
+
+          lhs == rhs
+        end
+
+        def truthy?(value)
+          !value.nil? && value != false
+        end
+
+        def class_of(value)
+          value.nil? ? "nil" : value.class.name
+        end
+
+        def match_include(expr)
+          index = expr.rindex(".include?(")
+          return nil unless index && expr.end_with?(")")
+
+          [expr[0...index], expr[(index + ".include?(".length)...-1]]
+        end
+
+        # Declared the same way in Vocabulary::IncludeHaystack
+        # (language/bluebook/vocabulary.bluebook) — spec/vocabulary_conformance_spec
+        # holds this equal to the language, so the set of haystack types
+        # `.include?` supports cannot drift from what the language says it
+        # does.
+        INCLUDE_HAYSTACKS = Hecks::Vocabulary.fetch("IncludeHaystack")
+
+        def includes?(parts, state, attrs)
+          haystack, needle = parts
+          wanted = Resolver.interpret(needle, state, attrs)
+
+          case (found = Resolver.interpret(haystack, state, attrs))
+          when Array then found.any? { |item| equal?(item, wanted) }
+          when String
+            unless wanted.is_a?(String)
+              raise EvaluationError, "no implicit conversion of #{class_of(wanted)} into String"
+            end
+
+            found.include?(wanted)
+          else false
+          end
+        end
+
+        def strip_parens(expr)
+          return expr unless expr.start_with?("(") && expr.end_with?(")")
+
+          depth = 0
+          expr.each_char.with_index do |char, index|
+            depth += 1 if char == "("
+            depth -= 1 if char == ")"
+            return expr if depth.zero? && index < expr.length - 1
+          end
+          strip_parens(expr[1..-2].strip)
+        end
+
+        def split_top_level(expr, operator)
+          index = top_level_index(expr, operator)
+          return nil unless index
+
+          [expr[0...index].strip, expr[(index + operator.length)..].strip]
+        end
+
+        def split_comparison(expr, operator)
+          index = top_level_index(expr, operator) { |at| !part_of_longer?(expr, at, operator) }
+          return nil unless index
+
+          [expr[0...index].strip, expr[(index + operator.length)..].strip]
+        end
+
+        def part_of_longer?(expr, index, operator)
+          after  = expr[index + operator.length]
+          before = index.positive? ? expr[index - 1] : nil
+
+          return true if after == "=" && !operator.end_with?("=")
+          return true if ["<", ">", "!", "="].include?(before) && operator.start_with?("=")
+
+          false
+        end
+
+        def top_level_index(expr, operator)
+          depth = 0
+          quote = nil
+          index = 0
+
+          while index < expr.length
+            char = expr[index]
+
+            if quote
+              quote = nil if char == quote
+            elsif ['"', "'"].include?(char)
+              quote = char
+            # `{`/`}` 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
+            # 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
+            # `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
+            # against) : the stray `>` split the expression in half
+            # before `Resolver.parse` ever saw the block as one atomic
+            # leaf, and the two halves then failed independently with
+            # the same raw `TypeError` the block-predicate fix was
+            # built to close. `{`/`}` cannot legitimately appear inside
+            # a quoted literal either, so this sits beside the existing
+            # paren-depth branch, not instead of it.
+            elsif char == "(" || char == "{"
+              depth += 1
+            elsif char == ")" || char == "}"
+              depth -= 1
+            elsif depth.zero? && expr[index, operator.length] == operator
+              return index if !block_given? || yield(index)
+            end
+
+            index += 1
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/expression/projection.json

@@ -0,0 +1,170 @@
+{
+  "operators": [
+    {
+      "symbol": "||",
+      "category": "logical",
+      "precedence": 1,
+      "arity": 2
+    },
+    {
+      "symbol": "&&",
+      "category": "logical",
+      "precedence": 2,
+      "arity": 2
+    },
+    {
+      "symbol": ".include?",
+      "category": "membership",
+      "precedence": 3,
+      "arity": 2
+    },
+    {
+      "symbol": ">=",
+      "category": "comparison",
+      "precedence": 4,
+      "arity": 2,
+      "compares_less_than": true,
+      "compares_equal": false,
+      "negated": true
+    },
+    {
+      "symbol": "<=",
+      "category": "comparison",
+      "precedence": 4,
+      "arity": 2,
+      "compares_less_than": true,
+      "compares_equal": true,
+      "negated": false
+    },
+    {
+      "symbol": "<",
+      "category": "comparison",
+      "precedence": 4,
+      "arity": 2,
+      "compares_less_than": true,
+      "compares_equal": false,
+      "negated": false
+    },
+    {
+      "symbol": ">",
+      "category": "comparison",
+      "precedence": 4,
+      "arity": 2,
+      "compares_less_than": true,
+      "compares_equal": true,
+      "negated": true
+    },
+    {
+      "symbol": "==",
+      "category": "comparison",
+      "precedence": 4,
+      "arity": 2,
+      "compares_less_than": false,
+      "compares_equal": true,
+      "negated": false
+    },
+    {
+      "symbol": "!=",
+      "category": "comparison",
+      "precedence": 4,
+      "arity": 2,
+      "compares_less_than": false,
+      "compares_equal": true,
+      "negated": true
+    },
+    {
+      "symbol": "!",
+      "category": "logical",
+      "precedence": 5,
+      "arity": 1
+    },
+    {
+      "symbol": "+",
+      "category": "arithmetic",
+      "precedence": 6,
+      "arity": 2
+    },
+    {
+      "symbol": ".modulo",
+      "category": "arithmetic",
+      "precedence": 6,
+      "arity": 2
+    },
+    {
+      "symbol": ".positive?",
+      "category": "sign_test",
+      "precedence": 7,
+      "arity": 1
+    },
+    {
+      "symbol": ".negative?",
+      "category": "sign_test",
+      "precedence": 7,
+      "arity": 1
+    },
+    {
+      "symbol": ".zero?",
+      "category": "sign_test",
+      "precedence": 7,
+      "arity": 1
+    },
+    {
+      "symbol": ".empty?",
+      "category": "sized",
+      "precedence": 8,
+      "arity": 1
+    },
+    {
+      "symbol": ".to_s",
+      "category": "to_string",
+      "precedence": 9,
+      "arity": 1
+    },
+    {
+      "symbol": ".size",
+      "category": "sized",
+      "precedence": 8,
+      "arity": 1
+    },
+    {
+      "symbol": ".any?",
+      "category": "enumeration",
+      "precedence": 10,
+      "arity": 2
+    },
+    {
+      "symbol": ".none?",
+      "category": "enumeration",
+      "precedence": 10,
+      "arity": 2
+    },
+    {
+      "symbol": ".all?",
+      "category": "enumeration",
+      "precedence": 10,
+      "arity": 2
+    },
+    {
+      "symbol": ".find",
+      "category": "enumeration",
+      "precedence": 10,
+      "arity": 2
+    }
+  ],
+  "normalisations": [
+    {
+      "strategy": "collapse_whitespace",
+      "source_token": "",
+      "replacement": "",
+      "boundary": "none",
+      "position": 1
+    },
+    {
+      "strategy": "replace",
+      "source_token": ".length",
+      "replacement": ".size",
+      "boundary": "word",
+      "position": 2
+    }
+  ]
+}

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

@@ -0,0 +1,233 @@
+# 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`
+# 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`,
+# `walk_path`) resolve exactly the way they do inside resolver.rb
+# itself — this is one module, split across two files, not two
+# modules. See resolver.rb's own header for the grammar this belongs
+# to; see each struct/method below for its own "why".
+module Hecks
+  module Bluebook
+    module Expression
+      module Resolver
+        # `receiver.all? { |x| PREDICATE }` / `.any? { ... }` / `.none? {
+        # ... }` -- vendored addition, not (yet) upstream hecks
+        # (migration plan task 9), completing the same `Phrase`
+        # four-segment invariant the `Split` node above was built for
+        # (`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
+        # 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
+        # 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
+        # every sibling node's sub-expressions are. `mode` distinguishes
+        # all?/any?/none? without three duplicated node types, since
+        # their only difference is which Array predicate aggregates the
+        # per-element results (interpret_with_element, below, is the
+        # "smallest correct thing" the plan asked for -- it threads the
+        # element binding through a temporarily-extended `attrs` hash for
+        # that one predicate's evaluation only, never touching
+        # `interpret`'s own signature or any other node's call sites).
+        # `Resolver` already calls into `Evaluator` elsewhere in this
+        # file (`sign_test_node`/`apply_sign_test` call `Evaluator.
+        # apply`/`Evaluator::OPERATORS` directly) -- this is the same
+        # precedented cross-reference, not a new coupling.
+        BlockPredicate = Struct.new(:mode, :receiver, :param, :predicate, keyword_init: true)
+
+        # Which Array method each block-predicate suffix maps to, and
+        # which Ruby Enumerable method decides the aggregate result --
+        # declared as data, not a three-way `case`, the same shape
+        # SIGN_TEST_OPERATORS above already uses for its own suffix
+        # family.
+        BLOCK_PREDICATE_MODES = {
+          "all?"  => :all,
+          "any?"  => :any,
+          "none?" => :none
+        }.freeze
+
+        # `receiver.find { |x| PREDICATE }` / `.find { ... }.a.b` -- the
+        # "find-then-project" shape the shipping domain's re-routing
+        # rules kept reaching for by hand (a caller-precomputed
+        # `next_load_location` field standing in for "the leg after this
+        # one", because `BlockPredicate` above can only answer yes/no,
+        # never hand back the element it found). `path` holds the
+        # dotted segments walked past the closing `}`, e.g. the `["
+        # next_load_location"]` in `legs.find { |l| l.load_location ==
+        # x }.next_load_location` -- empty when `.find { ... }` is used
+        # bare (its own found-element-or-nil is the value, same as any
+        # other leaf, e.g. composed with `.present?` the same way every
+        # other receiver already composes with it). Reuses `param`/
+        # `predicate`'s exact field names from `BlockPredicate` on
+        # purpose: `interpret_with_element` below binds by those two
+        # names and is shared unchanged between both node types.
+        Find = Struct.new(:receiver, :param, :predicate, :path, keyword_init: true)
+
+        module_function
+
+        # 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
+        # `evaluate_block_predicate` aggregates through, it builds a
+        # `Find` node instead, see below).
+        BLOCK_OPENER_SUFFIXES = (BLOCK_PREDICATE_MODES.keys + ["find"]).freeze
+
+        # `.all?`/`.any?`/`.none?`/`.find` -- vendored addition, see the
+        # `BlockPredicate`/`Find` structs' own comments above. Matched
+        # 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
+        # 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,
+        # 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
+        # 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
+        # `.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 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
+        # followed by `{`.
+        #
+        # `matching_brace` walks forward counting `{`/`}` depth from
+        # there, the same quote-aware, depth-aware discipline
+        # `split_addition`/`array_elements` already apply, so a `}`
+        # inside a nested block (or a quoted `start_with?` substring)
+        # never miscounts. `.find`'s own trailing dotted path (`path`)
+        # is captured from whatever follows the closing brace ; every
+        # other suffix instead requires nothing follow it at all (the
+        # `BlockPredicate` shape, unchanged from before this rewrite).
+        def parse_block_opener(expr)
+          pattern = /\A(.+?)\.(#{BLOCK_OPENER_SUFFIXES.map { |suffix| Regexp.escape(suffix) }.join('|')})\s*\{\s*\|(\w+)\|\s*/m
+          header = expr.match(pattern)
+          return nil unless header
+
+          receiver_text = header[1]
+          suffix = header[2]
+          param = header[3]
+          body_start = header.end(0)
+          body_end = matching_brace(expr, body_start)
+          return nil unless body_end
+
+          predicate = Evaluator.parse(expr[body_start...body_end].strip)
+
+          if suffix == "find"
+            trailing = expr[(body_end + 1)..].strip
+            return nil unless trailing.empty? || trailing.start_with?(".")
+
+            Find.new(receiver: parse(receiver_text), param: param, predicate: predicate,
+                     path: trailing.empty? ? [] : trailing[1..].split("."))
+          else
+            return nil unless expr[(body_end + 1)..].strip.empty?
+
+            BlockPredicate.new(mode: BLOCK_PREDICATE_MODES.fetch(suffix), receiver: parse(receiver_text),
+                               param: param, predicate: predicate)
+          end
+        end
+
+        # The index of the `}` that closes the `{` implicitly opened
+        # just before `start` (the caller's own header match already
+        # consumed that opening brace, so depth begins at 1) -- nil if
+        # the string runs out before depth returns to 0 (a caller-error
+        # shape, not a valid expression). Quote-aware so a `}` inside a
+        # quoted substring (`.start_with?("}")`) never miscounts, the
+        # same discipline `split_addition`/`array_elements` already
+        # apply for their own depth tracking.
+        def matching_brace(expr, start)
+          depth = 1
+          quote = nil
+          index = start
+          while index < expr.length
+            char = expr[index]
+            if quote
+              quote = nil if char == quote
+            elsif ['"', "'"].include?(char)
+              quote = char
+            elsif char == "{"
+              depth += 1
+            elsif char == "}"
+              depth -= 1
+              return index if depth.zero?
+            end
+            index += 1
+          end
+          nil
+        end
+
+        # `.all?`/`.any?`/`.none?` -- vendored addition, see the
+        # `BlockPredicate` struct's own comment above. `collection` is
+        # already-interpreted (a real Array, produced by whatever
+        # receiver expression came before it -- typically `Split`'s
+        # output), so this only has to run the per-element predicate and
+        # aggregate. `interpret_with_element` is the "smallest correct
+        # thing" the migration plan asked for : no persistent iteration-
+        # variable concept added anywhere else in Resolver's state model,
+        # just `attrs` extended with the bound name for the span of that
+        # one predicate evaluation, discarded immediately after.
+        def evaluate_block_predicate(node, collection, state, attrs)
+          unless collection.is_a?(Array)
+            raise EvaluationError, "#{node.mode}? expects a list, got #{describe(collection)}"
+          end
+
+          outcomes = collection.map { |element| interpret_with_element(node, element, state, attrs) }
+
+          case node.mode
+          when :all  then outcomes.all?
+          when :any  then outcomes.any?
+          when :none then outcomes.none?
+          end
+        end
+
+        # Binds the block parameter for exactly one element's predicate
+        # evaluation -- `attrs` wins over `state` in `fetch` (see below),
+        # so the bound name shadows any same-named state/attrs field for
+        # the span of this one call only ; nothing persists past it.
+        def interpret_with_element(node, element, state, attrs)
+          Evaluator.interpret(node.predicate, state, attrs.merge(node.param.to_sym => element))
+        end
+
+        # `.find { |x| PREDICATE }` -- see the `Find` struct's own
+        # 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
+        # `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
+        # resolve) flows through rather than raising — the same "a
+        # dispatch-time given just refuses" shape every other missing-
+        # value case in this grammar already has, and the one a re-
+        # routing check like "is there a leg after this one" needs :
+        # not finding one is a normal outcome, not an error.
+        def found_of(node, collection, state, attrs)
+          raise EvaluationError, "find expects a list, got #{describe(collection)}" unless collection.is_a?(Array)
+
+          found = collection.find { |element| interpret_with_element(node, element, state, attrs) }
+          return unwrap_scalar(found) if node.path.empty?
+          return nil if found.nil?
+
+          unwrap_scalar(walk_path(found, node.path))
+        end
+      end
+    end
+  end
+end