hecks 3.5.0 → 3.7.0

data/lib/hecks/grammar/evolve/seeds.rb

@@ -0,0 +1,172 @@
+module Hecks
+  module Grammar
+    module Evolve
+      # Reading the KeywordSeed and ArgumentSeed value-object blocks out of the syntax tables as
+      # text, and the row edits both kinds of row share. Extended onto `Hecks::Grammar::Evolve`.
+      module Seeds
+        # One `name: "value"` cell of a member row; the value may hold escaped quotes.
+        CELL = /(\w+): "((?:[^"\\]|\\.)*)"/
+
+        # Parses the Keyword one_of's member rows leniently off the text.
+        def keyword_rows(path = nil)
+          seed_rows(path, "KeywordSeed") do |row|
+            { word: row["word"], context: row["context"],
+              status: row.fetch("status", "admitted"), was: row["was"] }
+          end
+        end
+
+        # Parses the ArgumentSeed's member rows leniently off the text.
+        def argument_rows(path = nil)
+          seed_rows(path, "ArgumentSeed") do |row|
+            { keyword: row["keyword"], context: row["context"], at: row["at"].to_s,
+              named: row["named"].to_s, kind: row["kind"], required: row["required"],
+              fills: row["fills"].to_s, status: row.fetch("status", "admitted") }
+          end
+        end
+
+        # @param path [String, Array<String>, nil] the files to read; nil reads every syntax table
+        # @param name [String] the seed value object, `"KeywordSeed"` or `"ArgumentSeed"`
+        # @yieldparam cells [Hash{String => String}] one member row's cells
+        # @return [Array<Hash>] what the block makes of each member row
+        # @raise [Refusal] when files were named and one declares no such value object
+        def seed_rows(path, name)
+          paths_for(path).flat_map do |candidate|
+            blocks = seed_blocks(read_source(candidate), name)
+            raise Refusal, "source declares no #{name} value object" if path && blocks.empty?
+
+            blocks.flat_map { |block| block.scan(/^\s*member (.+)$/).map { |(cells)| yield cells.scan(CELL).to_h } }
+          end
+        end
+
+        # Tells whether `line` is a KeywordSeed member row for (word, context).
+        def member_row?(line, word, context)
+          line =~ /^\s*member / && line.include?(%(word: "#{word}")) && line.include?(%(context: "#{context}"))
+        end
+
+        # Tells whether `line` is an ArgumentSeed row for this (keyword, context, at, named) tuple.
+        def argument_row?(line, keyword, context, at, named)
+          line =~ /^\s*member / &&
+            line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}")) &&
+            line.include?(%(at: "#{at}")) && line.include?(%(named: "#{named}"))
+        end
+
+        # The (keyword, context, at, named) identity tuple an argument row is keyed
+        # by — wider than a Keyword row's two-field key.
+        def argument_identity(row) = [row[:keyword], row[:context], row[:at], row[:named]]
+
+        # Finds which syntax-table path declares a keyword row.
+        def path_holding_keyword(word, context, paths = syntax_paths)
+          paths.find do |candidate|
+            keyword_blocks(read_source(candidate)).any? do |block|
+              block.lines.any? { |line| member_row?(line, word, context) }
+            end
+          end || raise(Refusal, "#{context}.#{word} is not declared")
+        end
+
+        # Finds which syntax-table path declares an argument row.
+        def path_holding_argument(keyword, context, at, named, paths = syntax_paths)
+          paths.find do |candidate|
+            argument_blocks(read_source(candidate)).any? do |block|
+              block.lines.any? { |line| argument_row?(line, keyword, context, at, named) }
+            end
+          end || raise(Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not declared")
+        end
+
+        # Picks the owning file for a new row; opens names the aggregate for a File-context word.
+        def owner_path(context:, word:, opens: "", paths: syntax_paths)
+          opening_path(context, opens, paths) || paths.find { |candidate| declares_context?(candidate, context) } ||
+            raise(Refusal, "no aggregate-local syntax table owns context #{context.inspect} for #{word}")
+        end
+
+        # @return [String, nil] the file declaring the aggregate a File-context word opens
+        def opening_path(context, opens, paths)
+          return unless context == "File" && !opens.to_s.empty?
+
+          paths.find { |candidate| read_source(candidate).match?(/^\s*aggregate "#{Regexp.escape(opens)}" do$/) }
+        end
+
+        def declares_context?(candidate, context)
+          source = read_source(candidate)
+          %w[KeywordSeed ArgumentSeed].any? do |seed|
+            seed_blocks(source, seed).any? { |block| block.include?(%(context: "#{context}")) }
+          end
+        end
+
+        # Appends a member row, at the end of the seed block owning `context`, as `proposed`;
+        # whoever admits it may move it to its group.
+        #
+        # @param path [String] the file holding the block
+        # @param context [String] the context whose block takes the row
+        # @param seed [String] `"KeywordSeed"` or `"ArgumentSeed"`
+        # @yieldparam indent [String] the whitespace the block's member rows start with
+        # @yieldreturn [String] the new row, newline included
+        def append_member(path, context, seed)
+          source = read_source(path)
+          block = seed_blocks(source, seed).find { |candidate| candidate.include?(%(context: "#{context}")) } ||
+                  seed_block(source, seed, required: true)
+          indent = block[/^(\s*)member /, 1] || "        "
+          closing = block.rindex(/^\s*end\s*$/)
+          write_source(path, source.sub(block, block[0...closing] + yield(indent) + block[closing..]))
+        end
+
+        # Rewrites, through the block, each line of the seed block holding the rows `matches` picks.
+        #
+        # @param path [String] the file holding the block
+        # @param seed [String] `"KeywordSeed"` or `"ArgumentSeed"`
+        # @param matches [#call] tells whether a line is one of the rows to rewrite
+        # @param missing [String] the refusal when no row matches
+        # @raise [Refusal] when no row matches
+        def rewrite_member_rows(path, seed, matches, missing)
+          source = read_source(path)
+          block = seed_blocks(source, seed).find { |candidate| candidate.lines.any?(&matches) }
+          raise Refusal, missing unless block
+
+          updated = block.lines.map { |line| matches.call(line) ? yield(line) : line }.join
+          write_source(path, source.sub(block, updated))
+        end
+
+        # Sets a row line's `status:` cell; admitted is the default and stays unspelled.
+        def restatus(line, to)
+          stripped = line.sub(/,\s*status: "[^"]*"/, "")
+          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
+        end
+
+        # Every value_object "<name>" block's full source text, opener to closing end.
+        def seed_blocks(source, name)
+          opener = /^([ \t]*)value_object "#{Regexp.escape(name)}" do$/
+          source.to_enum(:scan, opener).map do
+            match = Regexp.last_match
+            start = match.begin(0)
+            closing = source.index(/^#{Regexp.escape(match[1])}end\s*$/, match.end(0))
+            closing = source.index(/\n/, closing) + 1
+            source[start...closing]
+          end
+        end
+
+        # The first value_object "<name>" block's source text.
+        def seed_block(source, name, required: false)
+          block = seed_blocks(source, name).first
+          unless block
+            raise Refusal, "source declares no #{name} value object" if required
+
+            return
+          end
+          block
+        end
+
+        # First `end` after the opener is the block's own — member rows sit bare (ADR 0025).
+        def keyword_blocks(source) = seed_blocks(source, "KeywordSeed")
+
+        # The first KeywordSeed block's source text.
+        def keyword_block(source) = seed_block(source, "KeywordSeed", required: true)
+
+        # ArgumentSeed blocks; see keyword_blocks for why the first bare end
+        # after the opener is already the block's own.
+        def argument_blocks(source) = seed_blocks(source, "ArgumentSeed")
+
+        # The first ArgumentSeed block's source text.
+        def argument_block(source) = seed_block(source, "ArgumentSeed", required: true)
+      end
+    end
+  end
+end

data/lib/hecks/grammar/evolve.rb

@@ -1,10 +1,24 @@
+require_relative "evolve/seeds"
+require_relative "evolve/keywords"
+require_relative "evolve/arguments"
+
 module Hecks
   module Grammar
     # File surgery under `hecks word_status` and its siblings: reads and rewrites the
     # aggregate-local KeywordSeed/ArgumentSeed rows as text, preserving the table's own formatting.
+    #
+    # The row readers and edits live in `Seeds`, `Keywords` and `Arguments`, extended onto this
+    # module; what is here is the reading and writing of the table files themselves.
     module Evolve
       class Refusal < StandardError; end
 
+      # The stations a word's or an argument's life admits.
+      STATIONS = %w[proposed admitted deprecated retired].freeze
+
+      extend Seeds
+      extend Keywords
+      extend Arguments
+
       module_function
 
       # Only consumes the next argv element as the value when it isn't itself
@@ -88,270 +102,15 @@ module Hecks
       # Resolves the file(s) a call should search or write.
       def paths_for(path) = path ? Array(path) : syntax_paths
 
-      # Parses the Keyword one_of's member rows leniently off the text.
-      def keyword_rows(path = nil)
-        paths_for(path).flat_map do |candidate|
-          blocks = seed_blocks(read_source(candidate), "KeywordSeed")
-          raise Refusal, "source declares no KeywordSeed value object" if path && blocks.empty?
-
-          blocks.flat_map do |block|
-            block.scan(/^\s*member (.+)$/).map do |(cells)|
-              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
-              { word: row["word"], context: row["context"],
-                status: row.fetch("status", "admitted"), was: row["was"] }
-            end
-          end
-        end
-      end
-
-      # Declares a new, proposed keyword row in the syntax table that owns
-      # `context` (or the aggregate `opens` names, for a File-context word).
-      def propose(word:, context:, body: "none", inner: "", opens: "", fills: "", path: nil)
-        if keyword_rows(path).any? do |row|
-          row[:word] == word && row[:context] == context
-        end
-          raise Refusal,
-                "#{context}.#{word} is already declared — one row per (word, context, form)"
-        end
-
-        path = owner_path(context: context, word: word, opens: opens, paths: paths_for(path))
-        source = read_source(path)
-        block  = keyword_blocks(source).find { |candidate| candidate.include?(%(context: "#{context}")) } || keyword_block(source)
-        indent = block[/^(\s*)member /, 1] || "        "
-        row = %(#{indent}member word: "#{word}", context: "#{context}", body: "#{body}", ) +
-              %(inner: "#{inner}", opens: "#{opens}", fills: "#{fills}", status: "proposed"\n)
-
-        # Appended at the end; whoever admits it may move it to its group.
-        closing = block.rindex(/^\s*end\s*$/)
-        updated = block[0...closing] + row + block[closing..]
-        write_source(path, source.sub(block, updated))
-      end
-
-      # Rewrites a declared keyword row's status: cell in place.
-      def set_status(word:, context:, to:, path: nil)
-        raise Refusal, "#{to.inspect} is not a station a word's life admits" unless %w[proposed admitted deprecated
-                                                                                       retired].include?(to)
-
-        path = path_holding_keyword(word, context, paths_for(path))
-        source = read_source(path)
-        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
-        rows   = block.lines.select { |line| member_row?(line, word, context) }
-        raise Refusal, "#{context}.#{word} is not declared" if rows.empty?
-
-        updated = block.lines.map do |line|
-          next line unless member_row?(line, word, context)
-
-          stripped = line.sub(/,\s*status: "[^"]*"/, "")
-          # Admitted is the default and stays unspelled in the row.
-          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
-        end.join
-
-        write_source(path, source.sub(block, updated))
-      end
-
-      # Respells a keyword row (was: holds the old spelling) — one hop only;
-      # its Argument rows follow, row-aware (see cascade_argument_rename).
-      def rename(word:, context:, to:, path: nil)
-        row = keyword_rows(path).find { |r| r[:word] == word && r[:context] == context }
-        raise Refusal, "#{context}.#{word} is not declared" unless row
-        raise Refusal, "#{context}.#{word} was already #{row[:was]} — one rename hop, then eras" if row[:was]
-        if keyword_rows(path).any? do |r|
-          r[:word] == to && r[:context] == context
-        end
-          raise Refusal,
-                "#{context}.#{to} is already declared — a rename cannot land on a living word"
-        end
-
-        paths = paths_for(path)
-        path = path_holding_keyword(word, context, paths)
-        source = read_source(path)
-        block  = keyword_blocks(source).find { |candidate| candidate.lines.any? { |line| member_row?(line, word, context) } }
-        updated = block.lines.map do |line|
-          next line unless member_row?(line, word, context)
-
-          line.sub(%(word: "#{word}"), %(word: "#{to}"))
-              .sub(/\n\z/, %(, was: "#{word}"\n))
-        end.join
-        source = source.sub(block, updated)
-        write_source(path, source)
-
-        cascade_argument_rename(keyword: word, context: context, to: to, path: paths)
-      end
-
-      # Tells whether `line` is a KeywordSeed member row for (word, context).
-      def member_row?(line, word, context)
-        line =~ /^\s*member / && line.include?(%(word: "#{word}")) && line.include?(%(context: "#{context}"))
-      end
-
-      # Finds which syntax-table path declares a keyword row.
-      def path_holding_keyword(word, context, paths = syntax_paths)
-        paths.find do |candidate|
-          keyword_blocks(read_source(candidate)).any? { |block| block.lines.any? { |line| member_row?(line, word, context) } }
-        end || raise(Refusal, "#{context}.#{word} is not declared")
-      end
-
-      # Finds which syntax-table path declares an argument row.
-      def path_holding_argument(keyword, context, at, named, paths = syntax_paths)
-        paths.find do |candidate|
-          argument_blocks(read_source(candidate)).any? do |block|
-            block.lines.any? do |line|
-              argument_row?(line, keyword, context, at, named)
-            end
-          end
-        end || raise(Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not declared")
-      end
-
-      # Picks the owning file for a new row; opens names the aggregate for a File-context word.
-      def owner_path(context:, word:, opens: "", paths: syntax_paths)
-        if context == "File" && !opens.to_s.empty?
-          aggregate_path = paths.find { |candidate| read_source(candidate).match?(/^\s*aggregate "#{Regexp.escape(opens)}" do$/) }
-          return aggregate_path if aggregate_path
-        end
-
-        paths.find do |candidate|
-          source = read_source(candidate)
-          %w[KeywordSeed ArgumentSeed].any? do |seed|
-            seed_blocks(source, seed).any? { |block| block.include?(%(context: "#{context}")) }
-          end
-        end || raise(Refusal, "no aggregate-local syntax table owns context #{context.inspect} for #{word}")
-      end
-
-      # Every value_object "<name>" block's full source text, opener to closing end.
-      def seed_blocks(source, name)
-        opener = /^([ \t]*)value_object "#{Regexp.escape(name)}" do$/
-        source.to_enum(:scan, opener).map do
-          match = Regexp.last_match
-          start = match.begin(0)
-          indent = match[1]
-          closing = source.index(/^#{Regexp.escape(indent)}end\s*$/, match.end(0))
-          closing = source.index(/\n/, closing) + 1
-          source[start...closing]
-        end
-      end
-
-      # The first value_object "<name>" block's source text.
-      def seed_block(source, name, required: false)
-        block = seed_blocks(source, name).first
-        unless block
-          raise Refusal, "source declares no #{name} value object" if required
-
-          return
-        end
-        block
-      end
-
-      # First `end` after the opener is the block's own — member rows sit bare (ADR 0025).
-      def keyword_blocks(source) = seed_blocks(source, "KeywordSeed")
-
-      # The first KeywordSeed block's source text.
-      def keyword_block(source) = seed_block(source, "KeywordSeed", required: true)
-
-      # Parses the ArgumentSeed's member rows leniently off the text.
-      def argument_rows(path = nil)
-        paths_for(path).flat_map do |candidate|
-          blocks = seed_blocks(read_source(candidate), "ArgumentSeed")
-          raise Refusal, "source declares no ArgumentSeed value object" if path && blocks.empty?
-
-          blocks.flat_map do |block|
-            block.scan(/^\s*member (.+)$/).map do |(cells)|
-              row = cells.scan(/(\w+): "((?:[^"\\]|\\.)*)"/).to_h
-              { keyword: row["keyword"], context: row["context"], at: row["at"].to_s,
-                named: row["named"].to_s, kind: row["kind"], required: row["required"],
-                fills: row["fills"].to_s, status: row.fetch("status", "admitted") }
-            end
-          end
-        end
-      end
-
-      # Declares a new, proposed argument row; pairs_shape marks a `pairs`
-      # argument that fills a whole key/value list, not a single field.
-      def propose_argument(keyword:, context:, kind:, required: "false", at: "", named: "", fills: "",
-                           pairs_shape: nil, path: nil)
-        if argument_rows(path).any? { |r| argument_identity(r) == [keyword, context, at, named] }
-          raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is " \
-                         "already declared — one row per (keyword, context, at, named)"
-        end
-
-        path = owner_path(context: context, word: keyword, paths: paths_for(path))
-        source = read_source(path)
-        block  = argument_blocks(source).find do |candidate|
-          candidate.include?(%(context: "#{context}"))
-        end || argument_block(source)
-        indent = block[/^(\s*)member /, 1] || "        "
-        shape = pairs_shape.to_s.empty? ? "" : %(pairs_shape: "#{pairs_shape}", )
-        row = %(#{indent}member keyword: "#{keyword}", context: "#{context}", at: "#{at}", ) +
-              %(named: "#{named}", kind: "#{kind}", required: "#{required}", fills: "#{fills}", ) +
-              shape + %(status: "proposed"\n)
-
-        closing = block.rindex(/^\s*end\s*$/)
-        updated = block[0...closing] + row + block[closing..]
-        write_source(path, source.sub(block, updated))
-      end
-
-      # Rewrites a declared argument row's status: cell in place.
-      def set_argument_status(keyword:, context:, to:, at: "", named: "", path: nil)
-        raise Refusal, "#{to.inspect} is not a station an argument's life admits" unless %w[proposed admitted deprecated
-                                                                                            retired].include?(to)
-
-        path = path_holding_argument(keyword, context, at, named, paths_for(path))
-        source = read_source(path)
-        block  = argument_blocks(source).find do |candidate|
-          candidate.lines.any? do |line|
-            argument_row?(line, keyword, context, at, named)
-          end
-        end
-        rows = block.lines.select { |line| argument_row?(line, keyword, context, at, named) }
-        if rows.empty?
-          raise Refusal, "#{context}.#{keyword}'s argument at #{at.inspect}/named #{named.inspect} is not " \
-                         "declared"
-        end
-
-        updated = block.lines.map do |line|
-          next line unless argument_row?(line, keyword, context, at, named)
-
-          stripped = line.sub(/,\s*status: "[^"]*"/, "")
-          to == "admitted" ? stripped : stripped.sub(/\n\z/, %(, status: "#{to}"\n))
-        end.join
-
-        write_source(path, source.sub(block, updated))
-      end
-
-      # Tells whether `line` is an ArgumentSeed row for this (keyword, context, at, named) tuple.
-      def argument_row?(line, keyword, context, at, named)
-        line =~ /^\s*member / &&
-          line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}")) &&
-          line.include?(%(at: "#{at}")) && line.include?(%(named: "#{named}"))
-      end
-
-      # The (keyword, context, at, named) identity tuple an argument row is keyed
-      # by — wider than a Keyword row's two-field key.
-      def argument_identity(row) = [row[:keyword], row[:context], row[:at], row[:named]]
-
-      # Row-aware rename cascade — updates only the argument rows that belong
-      # to the renamed keyword, not a blind gsub across the file.
-      def cascade_argument_rename(keyword:, context:, to:, path: nil)
-        paths_for(path).each do |candidate|
-          source = read_source(candidate)
-          original = source
-          argument_blocks(source).each do |block|
-            updated = block.lines.map do |line|
-              next line unless line =~ /^\s*member / &&
-                               line.include?(%(keyword: "#{keyword}")) && line.include?(%(context: "#{context}"))
-
-              line.sub(%(keyword: "#{keyword}"), %(keyword: "#{to}"))
-            end.join
-            source = source.sub(block, updated) if updated != block
-          end
-          write_source(candidate, source) if source != original
-        end
+      # Refuses a keyword a call was not declared to take, as a method with those keywords would.
+      #
+      # @param fields [Hash] the keywords the caller passed
+      # @param allowed [Array<Symbol>] the keywords the call takes
+      # @raise [ArgumentError] naming the first keyword not in `allowed`
+      def check_fields!(fields, allowed)
+        unknown = fields.keys - allowed
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
       end
-
-      # ArgumentSeed blocks; see keyword_blocks for why the first bare end
-      # after the opener is already the block's own.
-      def argument_blocks(source) = seed_blocks(source, "ArgumentSeed")
-
-      # The first ArgumentSeed block's source text.
-      def argument_block(source) = seed_block(source, "ArgumentSeed", required: true)
     end
   end
 end

data/lib/hecks/grammar/operators.rb

@@ -0,0 +1,111 @@
+module Hecks
+  module Grammar
+    # Finds the operators the language's own guards and invariants evaluate through, by walking
+    # the evaluator's parse of each canonical expression. Extended onto `Hecks::Grammar`.
+    module Operators
+      # The operators the language's own guards and invariants (Bluebook, World and
+      # the grammar chapters) evaluate through. Retiring one would leave the
+      # language unable to read its own rules, so callers refuse it by name.
+      #
+      # @return [Hash{String => Array<String>}] each self-bearing operator symbol
+      #   mapped to the `"Chapter Aggregate.command"`/`"Chapter Aggregate::ValueObject"`
+      #   sites that use it
+      def self_bearing_operators
+        sites = Hash.new { |h, k| h[k] = [] }
+        language_chapters.each do |chapter|
+          chapter.aggregates.each do |aggregate|
+            (command_sites(chapter, aggregate) + value_object_sites(chapter, aggregate)).each do |symbol, site|
+              sites[symbol] << site
+            end
+          end
+        end
+        sites.transform_values(&:uniq)
+      end
+
+      # @return [Array<Class>] the Bluebook and World chapters plus every grammar chapter
+      def language_chapters
+        chapters = Bluebook::MetaValidator.grammar_registry
+                                          .then { |reg| %w[Bluebook World].map { |name| reg.bluebook(name) } }
+        (chapters + grammar_chapters).compact
+      end
+
+      # @return [Array<Array(String, String)>] each operator a command's givens use, with the
+      #   command it is used in
+      def command_sites(chapter, aggregate)
+        aggregate.commands.flat_map do |command|
+          site = "#{chapter.name} #{aggregate.name}.#{command.hecks_name}"
+          command.givens.flat_map { |given| operators_in(given.canonical).map { |symbol| [symbol, site] } }
+        end
+      end
+
+      # @return [Array<Array(String, String)>] each operator a value object's invariants use,
+      #   with the value object it is used in
+      def value_object_sites(chapter, aggregate)
+        aggregate.value_objects.flat_map do |value_object|
+          site = "#{chapter.name} #{aggregate.name}::#{value_object.hecks_name}"
+          value_object.invariants.flat_map { |invariant| operators_in(invariant.canonical).map { |symbol| [symbol, site] } }
+        end
+      end
+
+      # Every grammar/*.bluebook chapter, each booted alone in a scratch registry.
+      #
+      # @return [Array<Class>] each grammar chapter, booted alone in its own scratch
+      #   registry
+      def grammar_chapters
+        Dir[File.join(Grammar::DIR, "*.bluebook")].map do |chapter|
+          registry = Runtime::Registry.new
+          load_chapter(registry, chapter)
+          registry.bluebooks.values.first
+        end
+      end
+
+      # Which admitted operators one canonical text evaluates through, found by
+      # walking the evaluator's own parse.
+      #
+      # @param canonical [String] canonical expression text to parse
+      # @return [Array<String>] operator symbols the expression evaluates through, or
+      #   `[]` when `canonical` fails to parse
+      def operators_in(canonical)
+        evaluator = Bluebook::Expression::Evaluator
+        begin
+          node = evaluator.parse(canonical)
+        rescue StandardError
+          return []
+        end
+        walk_operators(node, evaluator).uniq
+      end
+
+      # One rule per closed node type of the AST, kept together so the whole operator
+      # vocabulary reads in one place.
+      # @param node [Object] an evaluator/resolver AST node, or a Struct fallback
+      # @param evaluator [Module] `Bluebook::Expression::Evaluator`, passed through
+      #   so nested calls don't re-resolve the constant
+      # @return [Array<String>] operator symbols found in `node` and its children
+      def walk_operators(node, evaluator)
+        _type, operator, readers = operator_rules(evaluator).find { |type, *| node.is_a?(type) }
+        return struct_operators(node, evaluator) unless readers
+
+        own = operator.respond_to?(:call) ? [operator.call(node)] : Array(operator)
+        own + readers.flat_map { |reader| walk_operators(node.public_send(reader), evaluator) }
+      end
+
+      # @return [Array<Array>] each node type with the operator it contributes (a String, a
+      #   callable reading it off the node, or nil) and the readers of its child nodes
+      def operator_rules(evaluator)
+        resolver = Bluebook::Expression::Resolver
+        [[evaluator::Or, "||", %i[left right]], [evaluator::And, "&&", %i[left right]],
+         [evaluator::Not, "!", %i[node]], [evaluator::Compare, ->(node) { node.operator.symbol }, %i[left right]],
+         [evaluator::Include, ".include?", %i[haystack needle]], [evaluator::Resolve, nil, %i[expr]],
+         [resolver::Addition, "+", %i[left right]], [resolver::Modulo, ".modulo", %i[receiver divisor]]]
+      end
+
+      # @return [Array<String>] operators found in the members of a Struct node; none for any
+      #   other node
+      def struct_operators(node, evaluator)
+        return [] unless node.is_a?(Struct)
+
+        node.members.flat_map { |member| walk_operators(node[member], evaluator) }
+      end
+    end
+  end
+end